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Prefe 



This manual describes the RL5I linker and locator and the L1B51 librarian for 
program modules produced by MCS-51 language translators such as ASM51 and 

PL/M-51. 

The RL51 and the LIB51 program operate on an Intel development system with an 
8080 or 8085 processor. The configuration must include 64K of RAM, a console, and 
at least one diskette or hard disk drive. 

NOTE 

In this manual, the term MCS-5 1 refers to all members of the MCS-51 family 
of microcomputers and to the software development tools for the MCS-51 

family. 



Reader's Guide 

The manual is organized into six chapters and five appendixes: 

Chapter 1 discusses the advantages of modular programming and summarizes the 
process of modular programming with the MCS-51 development tools. 

Chapter 2 reviews the mechanics of linkage and location for the RL51 program. 

Chapter 3 gives the details on invoking the linker/locator. 

Chapter 4 discusses the Tiles and displays produced by the RL51 program, with 
examples. 

Chapter 5 contains three examples of programs, with the link and locate steps for 
each program. 

Chapter 6 describes the LIBS I . the MCS-51 library manager and its usage. 

Appendix A presents the syntax of the RL51 commands with brief definitions of the 

controls. 

Appendix B lists the error messages and warnings displayed by RL5I, with suggestions 
for corrective action. 

Appendix C lists a summary of LIBS I commands. 

Appendix D lists the error messages generated by LIB51, with suggestions for 
corrective action. 

Appendix E contains hexadecimal-decimal conversion tables as a convenient reference. 



Related Publications 

The following list provides the manual title and order number for all Intel software 
development tools that run on DOS systems. Note that some manuals have two 
formats and two order numbers. One version of the manual is provided in a binder. 
This version is not sold separately; it can only be purchased when purchasing a 
software product. The second version, which has a soft cover, is sold separately. Use 
the soft cover number when ordering a manual separately. 
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Manual Title 


Binder 


Soft Cover 


MCS°-5I Macro Assembler User's Guide for DOS 
Systems 


122753 


122752 


PL/M-51 User's Guide for DOS Systems 


122742 


122743 


MCS*-5I Family of Single-Chip Microcomputers 
User's Manual for DOS Systems 




121517 


MCS*-5I Macro Assembly Language Pocket 
Reference for DOS Systems 




122755 


MCS"-5I Utilities Pocket Reference for DOS 
Systems 
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Notational Conventions 

UPPERCASE Characters shown in uppercase must be entered in the order 

shown. Enter the command words as shown, or use a system- 
defined abbreviation. You may enter the characters in upper- 
case or lowercase. 



italic 



directory-name 



Italic indicates a meta symbol that may be replaced with an 
item t hat fulfills the rules for that symbol. The actual symbol 
may be any of the following: 

Is that portion of a pathname that acts as a file locator by 
identifying the device and/or directory containing the 
filename. 



filename Is a valid name for the part of a pathname that names a file. 

system-id Is a generic label placed on sample listings where an oper- 

ating system-dependent name would actually be printed. 

Vx.y Is a generic label placed on sample listings where the version 

number of the product that produced the listing would 
actually be printed. 

I ] Brackets indicate optional arguments or parameters. 

< > One and only one of the enclosed entries must be selected 

unless the field is also surrounded by brackets, in which case 
it is optional. 

( >... At least one of the enclosed items must be selected unless the 

field is also surrounded by brackets, in which case it is 
optional. The items may be used in any order unless other- 
wise noted. 

I The vertical bar separates options within brackets [ ] or 

braces < > . 



[....] 



Ellipses indicate that the preceding argument or parameter 
may be repealed. 

The preceding item ma> be repealed, but each repetition must 
be separated by a comma. 
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punctuation Punctuation other than ellipses, braces, and bracket, must be 

en ercd as shown. For example, the punctuation shown in the 
following command must be entered: 

SUBMIT PLM86CPR0GA , SRC , '9 SEPT 81') 

lilll ^HHI I" j"|>n«h« wampte,, user input lines are printed in white 
on black to differentiate them from system output. 



Indicates a carriage return. 
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The Advantages of Modular Programming 

Many programs art too long or complex to write as a single unit. Programming 
becomes much simpler when the code is divided into small functional units. Modular 
programs are usually easier to code, debug, and change than monolithic programs. 

The modular approach to programming is similar to the design of hardware that 
contains numerous circuits. The device or program is logically divided into "black 
boxes" with specific inputs and outputs. Once the interfaces between the units have 
been defined, detailed design of each unit can proceed separately. 



Efficient Program Development 

Programs can be developed more quickly with the moduli! approach because small 
subprograms are easier to understand, design, and lest than large programs With the 
module inputs and outputs defined, the programmer can supply the needed input and 
verify the correctness of the module by examining the output. The separate modules 
are then linked and located into one program module. Finally, the completed program 
is tested. 



Multiple Use of Subprograms 

Code written for one program is often useful in others. Modular programming allows 
these sections Id be saved for future use. Because the code is relocatable, saved modules 
can be linked to any program that fulfills their input and output requirements. With 
monolithic programming, such sections of code are buried inside the program and are 
not so available for use by other programs. 

If you put your frequently-used subprograms into a library, RL5I will take care to 
load only those you need. Thus, you can save RAM and ROM without having to 
keep track of what is needed and what is not. 



Ease of Debugging and Modifying 

Modular programs are generally easier to debug than monolithic programs. Because 
the modular interfaces are well-defined, problems can be isolated to specific modules. 
Once the faulty module has been identified, fixing the problem is considerably simpler. 
When a program must be modified, modular programming simplifies the job. You 
can link new or modified modules to the existing program with confidence that the 
rest of the program will not be changed. 



MCS®-51 Modular Program Development Process 

This section is a brier review of the program development process using an MCS-5I 
language translator (e g., the relocatable MCS-5I assembler or PL/M-5I compiler), 
linker/locator, code converter programs. PROM programmer, and ICE***-5I in-circuil 
emulator. The process is shown in figure l-l. 



-2 MCS®-51 



cowmen 




1?|73M 

Figure 1-1. MCS"-51 Program Development Process 



Segments, Modules, Libraries, and Programs 

In the initial design stages, the tasks to be performed by the program are defined and 
then partitioned into subprograms. Here are brief introductions to the kinds of 
subprograms used with the MCS-5I assembler and linker/locator. 

A segment is a unit of code or data memory. A segment may be relocatable or 
absolute. A relocatable segment in a module can be a complete segment or can be a 
"partial" segment to be combined with other partial segments from other modules. 
A relocatable segment has a name, type, and other attributes that allow the linker to 
combine it with other partial segments, if required, and to correctly locale the segment. 
An absolute segment has no name and cannot be combined with other segments. See 
Chapter 2 for more detail on partial segments. 

A module contains one or more segments or partial segments. A module has a name 
assigned by the user. The module definitions determine the scope of local symbols. 
An object file contains one or more modules. You can add modules to a file by trans- 
fering the new modules from their individual files to another file. 

A library is a file that contains one or more modules. A library file is internally 
marked as a library, so RL5I can easily identify it as such. RL5I selects, out of the 
modules in the library, only those previously referenced Libraries are created using 
the LIB51 utility, which is described in detail in Chapter fi 

A program consists of a single absolute module, merging all absolute and relocatable 
segments from all input modules. The name of the output module produced by RL5I 
can be defined by the user or allowed to default to the name of the first input module. 
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Entering and Editing Source Modules 

m[o e so'urce C n g r i :. COmplcled ' ' he edi '° r « your .system to code the modules 
mo source files. The source modules are coded in assembly language or a high-level 

IX'fJe" " PL/M - M ' edi, ° r 3,50 be U " d 10 ™ ke corrcctionfin the 



Assembly and Compilation 

SLSHS ? S T M) L nd C ° mpiler W ,ri "" la " lh < code into 

« n M J M object file. The ASM 5 1 object file is reloca.a- 

blc when at least one input segment is relocatable: otherwise the object file is an 
absolute fi e. The PL/M-51 object file ,s al»avs relocatable The assembler nnd 

aTm P M«PL P /M^ ' liS,mg $h0W ' np ,he - u " s ° f lh < -nsh„;:n When 
ASM? I ,r PL/M-51 ,„ vocation contains the DEBUG control, the object file -ilso 

ubh and mher inr " r ™" u " r « »* * 



Relocation and Linkage 

Afier translation of all modules of the program, the linker/locator. RLM processes 

with the same name, then assigns absolute memory localions to all the relocatable 
segments. R L5 1 also resolves all references between modules, using the hW fita 
fil e h u'cr ""if' ' r ° r , ,hlS /"" lu "- R L-M outputs an absolute objec mod 

su ,s f the 7i S „ I' T" C,ed Pr ° gram ' 3 SUmmary ' l5tin 8 rile 5h ° wi "« <»* 
/k ^?'f pr0CeSS ' mc,udin e ' memor >' >"«P. symbol table and 
optionally, an inter-module cross-reference (IXREF) listing. 



ROM and PROM Versions 

MCS ^Pilu^ m0dU ' e Pr0duced b > RL?I « * loaded into members of the 
MCS-M family of microcomputers. For ROM versions of the microcomputer the 
program ,s masked into ROM during the manufacturing process. Fo PROM c 
and versions withno on-chip CODE memory, a PROM programmer is used to load 
the absolute module into program memory accessible 10 the microcomputer for 
«ecut»n. Refer to the MCS-M Family if Singh CHi n AficZT r ZTj< ™ 
Manual for details on the versions of microcomputers available 



ICE "-51 In-Circuit Emulator 

The ICE-5I in-circuit emulator is used for software and hardware debugging and 
M tegra ion into the final product. The absolute object modules produced ' 

Zf^STJSSP memory for " ecu,ion - Refer 10 ,he ICE - 5 1 — 1 



Keeping Track of Files 
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can use .LST, the default extension given by the translator. RL51 uses .Mjl for the 
default listing file extension (in order not to destroy the ASM51 listing Hie with the 
.LST extension). 

Library files customarily have the extension .LIB. 

Use caution with the extension .TMP, as many utilities (including RL5I and LIB5I) 
create temporary files with this extension. These utilities will delete your Hie if il has 
the same name and extension as the temporary files they create. 



The Mechanics of Linkage and 
Location with RL51 




This chapter describes the operation of the RL51 program. Most of the process is 
transparent to the user; however, an understanding of the operation at the level 
presented here will help you lo use the linking and locating controls in the RL5I 
invocation. More specific details on the allocating process appear in Chapter 3. 



Major Functions 

The RL5I program performs the following major functions: 

1. Selects modules (including library processing) 

2. Combines relocatable partial segments of the same name into a single segmenl 

3. Allocates memory for ihe combined segments resulting from the previous step, 
and for all other complete relocatable segments from ihe input modules 

4. Overlays data segments 

5. Resolves external svmhol references between the input modules 

6. Binds relocatable addresses lo absolute addresses 

7. Produces an absolute object file 

R, Produces a listing file consisting of a link summary, a symbol lahle, and an IXRI.I 
report 

9. Detects and lists errors found in the input modules or in Ihe RL5I command 

invocation 

Functions I. 2, 3, 5. and 6 are described in the remainder of this chapter. Functions 
7. 8. and 9 arc discussed in Chapter 4: the RL5I command invocation and overlaying 
of data segmenls are described in Chapter 3. 



Selecting Modules 

Input files are processed in the order they are specified in the invocation command. 

The processing of an input file varies according lo the content — that is, whether it is 
a library or non-library file. A non-library file may contain a concatenation of zero 
or more object modules. A library file contains zero or more object modules together 
with control information. A module in a non-library file is processed if it was explic- 
itly listed in the module list, or if the module list was not specified at all (in other 
words, as if all modules were listed implicitly). 

The processing of a library Tile is more complicated. If a module list was speciFied 
for the library file, then il is processed in the same manner as a non-library File. If a 
module list was not specified, then the library file is processed only if the previously 
processed modules contained at least one unresolved external. The library is scanned 
for modules containing public symbols that match as yet unresolved externals. Each 
such module is processed as if it were explicitly specified. The selection process 
continues until the modules in Ihe library cannot satisfy any unresolved externals 
(including an> externals encountered while processing modules from ihe library). 

RL5I will report an error if the same module name is encountered more than once 
during ihe link process. 
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Take TRIGON.LIB as an (utterly fictitious) example. Assume it contains procedures 
called SINE, COSINE, TANGENT, ARCSINE. ARCCOS. ARCTAN, HYPER- 
BOLIC-SINE, and HYPERBOLIC-COSINE. 

When RL5I starts processing TRIGON.LIB, it has already made a first pass over 
all files that appear before it in the invocation line. If one of these contains a refer- 
ence to the external SINE, and there is no public by that name, RL5I will assume 
that the procedure SINE from TRIGON.LIB is to be loaded. Otherwise, it will leave 
SINE alone for the moment. 

If, while loading from TRIGON.LIB. RL5I encounters new externals that a module 
in the library can resolve, it will scan the library once more. Thus, there is no logical 
order among modules in a library; they are all equal. If TANGENT calls SINE and 
COSINE, and they are in the same library, in any order whatsoever, a reference to 
TANGENT will cause all three to be loaded. 



Partial Segments 

A segment is a unit of code memory or data memory The portion of a segment 
defined in one module is called a partial segment. A partial segment has the following 
attributes (defined in the source module): 

• Name. A relocatable segment has a name by which it is linked with other portions 
of the same segment from other modules. Absolute segments do not have names. 

• Type. The type identifies the address space to which a segment belongs: CODE. 
XDATA. DATA, IDATA, or BIT. 

• Relocatabilily. For relocatable segments onlv, this altrihuic describes any special 
constraints on relocation (PAGE, INPAGE. BLOC K, BITADDRESSABLE, or 
UNIT). 

• 'Silt. The Size of the segment in bytes or bits, depending on the type. 

• Base Address. The lowest address in the partial segment. Tor absolute segments, 
the base address is assigned at assembly time; for relocatable segments, it is 
assigned at location lime. 

Absolute segments are complete segments: they are taken as is into the output module. 
Relocatable segments are either defined by ASM5I users (using the SEGMENT 
directive in the source module) or automatically generated by the PL/M-5I compiler. 

Refer to the MCS-51 Macro Assembler User's Guide Tor details on the assembler 
directives. 



Combining Relocatable Segments 

After processing the invocation command. RL5I performs a first pass over the input 
modules identified id the command. Pass 1 generates a segment table, a publics table, 
and an unresolved externals table. The segment table is discussed in this section: the 
other two tables are discussed later in this chapter. 

The segment table contains the name, length, type, and relocation attribute of all 
combined segments from all modules. Combined segments are produced from the 
partial segments in the input modules according to the following rules: 

• RL51 combines all partial segments with the same name into one relocatable 
segment. For example, if three input modules each have a partial relocatable 
segment named STACK, the segment table will have one segment named STACK 
that combines the length of the three partial segments. 
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All the partial segments to be combined must be of the same type (CODE. DATA. 
IDATA. XDATA, or BIT). If any partial segments have the same names but 
different types, an error occurs. 

• The length of the combined segment must not exceed the physical size of the 
memory type. Details on maximum size appear later in this chapter. 

The relocation attributes of all the partial segments to be combined must either 
be the same or UNIT-aligned combined with one other attribute. The combined 
segment receives the relocation attribute shared by the input partial segments, 
or, if the segments have attribute UNIT-aligncd combined with one other attrib- 
ute, the combined segment receives the more restrictive attribute. 

For example, if the three partial segments named STACK have relocation attri- 
butes LIN IT. PAGE, and UNIT, the combined segment has attribute PAGE 
(i.e., page-aligned). Note that the relocation attribute is applied to the combined 
segment, not to each component segment. To continue the example, since the 
relocation is PAGE, the combined segment will start on a page boundary, hut 
the component segments will be packed together without any gaps. 



Allocating Memory for Segments 

After the segment table is complete. RL5I can locate the segments within the memory 
spaces. Table 2-1 shows the address spaces used by MCS-51 processors, and the 
corresponding segment types. 

The allocation process has a definite sequence: the exact order is presented in 
Chapter 3. As an overview, the process follows a general pattern of rules as follows: 

1. Each of the types of memory space is allocated independent of the other spaces. 

2. Within each space, absolute segments are allocated first, then segments specified 
within locating controls in the RL5I command, then other relocatable segments. 

3. Because the on-chip data space represents three overlapping address spaces 
(DATA. IDATA, and BIT), the general pattern in rule 2 is modified. 

a. Absolute BIT. DATA, and IDATA segments, and register banks are allocated 

first. 

b. Segments specified in PRECEDE and BIT controls are allocated next, then 
other relocatable BIT (and BIT-ADDRESSABLE) segments (following 

rule 2). 

c. DATA type segments are allocated next; segments in the DATA control first, 
then other relocatable DATA segments. 

d. I DATA type segments (except ''STACK) are allocated next: segments in the 
IDATA control first, then other relocatable IDATA segments. 

c. Segments specified in the STACK control are allocated, at as low an address 
as possible, provided that it is above all BIT. DATA, and IDATA segments 
allocated under (c) and (d). 

f. Last, the segment 7STACK. if it exists and is IDATA. and is not mentioned 
in an explicit location control, is now- allocated, at as low an address as possi- 
ble, provided that it is above all BIT. DATA, and IDATA segments allocated 
under (c) and (d) and (e). 

In most cases, you do not need to use any explicit controls to obtain a satisfactory 
allocation of segments. RL5I tries to fit your segments into the designated memory 
spaces as best it can following the rules. As you can see. most of the complexitj 
occurs in the on-chip data space. 
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Table 2-1 . Address Spaces and Sequent Types 



Memory Space 


Maximum Size 


Addressee 


Segment Type 


Code 


64 K bytes 


0OO0H - OFFFFH 


CODE 


External dala 


64K bytes 


OOOOH - OFFFFH 


XDATA 


On-chip data 
(direct addressing) 


128 bytes 


00H - 7FH 


DATA 


On-chip data 
(indirect addressing) 


256 bytes 
(see t) 


OOH - OFFH 


IDATA 


Bit space in 
on-chip data 
memory 


126 bits 
(see 2) 


OOH - 7FH 


BIT 



1, The amount ot Indirectly addressable on-chip data memory is machine-dependent within the 
MCS-51 microcomputer lamiiy (see the discussion ot RAMSIZE control in Chapter 3). 

2. This bit space overlaps byte addresses 20H - 2FH in on-chip dala memory 

Note: Addresses in the SDeciai lunction register memory (direct data addresses 60H - OFFH. bit 
addresses 80H - OFFH) cannot be relocated: they are always apsoiute Thus, these addresses 
are not referenced in this table. 



Rule (f) applies lo PL/M-51. PL/M-.M produces for the stack an I DATA segment 
called 7STACK, whose size is I. Although, by applying rule (f). RL5I makes the 
slack as big as possible, it is the user responsibility to ensure that the size of the slack 
is large enough (the segment map shows where the stack is located). 



No rules for the allocation process can guarantee an optimal solution. If you arc short 
of memory and RL5l's first try is not satisfactory you can place the segments in 
memory using the locating controls. Details on the locating controls are given in 
Chapter 3. 



Overlaying Data Segments 

On-chip RAM is a scarce resource on the MCS-51. To economize, the PL/M-51 
compiler overlays dala segments in the compiled module. RL-51 completes the work 
by overlaying the dala segments across modules. This is accomplished by using the 
OVERLAY control. If RL-51 informed you about ignored segments due lo lack of 
on-chip RAM. try this control. The use of OVER LA Y is. in general, straightforward 
However, for complex applications (for example, those wilh mixed ASM-.M and 
PL/M-51 modules), consult Chapter 3. 



Resolving External References 

An external reference points lo a location in another module. The EXTERNAL 
declaration for symbols tells R L? 1 that the reference is lo a location defined in another 
module. In the latter module, the symbol is declared PUBLIC so that external refer- 
ences to that symbol in other modules can be satisfied. 

As il processes the input modules. RL.51 builds a tabic of public symbols and 
unresolved external references As each public. s> mbol is added lo the table, any 
external references lo that symbol are deleted. Alter all segments have been located, 
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the public ssmhiils arc bound lo absolute addresses. RL5I issues a warning for any 
unresolved externals that remain in the table. 

F.xternal symbols and corresponding public symbols must be compatible. That is. both 
must be defined to address the same address space, or at least one must be defined 
as a typeless symbol (NUMBER); and if the symbol represents a PL/M-51 proce- 
dure name, then both must share ihc same register bank (i.e.. must be declared within 
the l'L/M-51 source modules with the same USING attribute). 



Binding Relocatable Addresses 

After allocating memory for the combined segments and binding the public symbols. 
RL5I makes a second pass (pass 2) through Ihc input modules lo build the listing 
file and fixup (i.e.. bind to absolute addresses) any relocatable or external references. 
At this point. RL5I also processes debug records if requested, and performs fixups to 
any relocatable debug symbols that require processing to compute their absolute 
addresses. 



! 



Using the RL51 Program 

Introduction 

The RL.M program performs two functions for MCS-5I programs: 

• The link function, combining a number of object modules specified in an input 
list into a single object module in an output Hie 

The locate function, assigning absolute addresses to any relocatable addresses in 
the input modules 

This chapter explains how to enter commands, how to continue a long command onto 
more than one input line, how to enter comments in the invocation, and how to use 
abbreviations of the command words. 

The chapter then presents a summary of the format of the RL5I invocation command, 
followed by details on the elements of the command with examples. 



RL51 Command Format Summary 

Here is a summary of the syntax of the RL5I invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL51 command has the overall format: 

[ directory i device) R L 5 1 input-list t T output-file) [ control-list) 
where 

directory) device is the directory or device where RL51 resides. 

input-list is a list of filenames separated by commas. The files named 

in input-list should contain the relocatable modules to be linked 
and located in the final absolute output module. For each 
file, you can additionally specify which modules are to be 

included. 

output-lile is the name of the file that is to receive the output module. If 

you omit this entry, the program will supply a default name 
based on the first filename in the input list. 

control-list selects options for listing, linking, and locating the output. 

The listing controls specify what information is to be sent to 
the listing file, and the page width to be used. The linking 
controls specify the name of the output module, and deter- 
mine what debug information is to be placed in the output 
file. The locating controls allow you to assign absolute 
addresses to relocatable segments, and to specify the order of 
relocatable segments within a given type of memory. The 
configuration control is used to describe the actual configu- 
ration the object is aimed to. The overlay control overlays 
data segments between modules. 



The next several sections give details and examples of the elements of the RL5I 
command. Table 3- 1 gives brief definitions of some of the terms used in the controls. 
A list of abbreviations for command words appears at the end of the chapter. 
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Table 3-1 . Definitions of Common Terms 



T«rm 


Definition 


name 


Names can be from 1 to 40 characters m length and must be 
composed ol letters A - Z. digits • 9, or special characters (t t @. 
_). The first character must be a letter o' a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid Mename reference or device reference See next two items 
for examples. 


filename 


A reference to a disk IWe. 


device 


A reference to a non-disk device. 
Examples: :LP\ ;CO:, :TO: 


value 


A 16-bit unsigned integer. 

Examples 1 01 1 B. 304Q, 4096D (or just 4096), 0C300H 


address 


Same as value. 



Invocation 

The RL5I command is a standard operating system invocation. Terminate the 
command with the RETURN key. Note that the termination carriage return is not 
shown in the command formal notation. 

You can continue the invocation line on one or more additional lines by entering the 
ampersand (&) before you enter the line terminator. The next line then automati- 
cally appears with the continuation prompt. Comments can also be entered on the 
invocation line by placing the comments after the ampersand or semicolon (;) because 
the compiler ignores all characters that appear after the ampersand or semicolon but 
before the carriage return/line feed that terminates the line. 

Refer to your DOS user's guide for information on submitting batch file commands. 

Input List 

The input list tells RL5I what files are to be processed. The files must be disk files 
containing relocatable object modules as described in Chapter 2. 

The entry for each file in the list can include the following information: 

• The directory or device. If the directory or device is omitted, the default directory 
or device is assumed. 

• The filename. The filename is the name of the object file including an extension 
if one exists. 

• A list of modules enclosed in parentheses. If a module list is provided, only the 
modules in the list are linked into the output file, and modules not in the list are 
ignored. If no module list is provided, the default for a non-library file is to link 
all modules in the file into the output module. The default for a library file is to 
link only those modules that satisfy previously declared external symbols (see the 
exact process in Chapter 2 under "Selecting Modules"). 

If a module named in the module list is not present in the file, the system issues an 
error message but does not halt the link process. 

Module names (specified explicitly or implicitly) must be unique throughout the entire 
application. 
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Examples 

Following are examples of the RL5I input list— 

1. > R L 5 1 A : p r o g , o b j TO A : p r o g . a b s 

In this example, the input list has one file (prog.obj in directory A:): RL5I links 
all the modules in this Tile into the output Tile (prog.abs). (For clarity, this and 
other examples omit the directory in which RL51 resides; the examples assume 
RL5I resides in the root directory.) 

2. >RL51 aisampl.obj, a: ji«p2.ob| , a : s a «i p 3 . o b ] I 
>> TO bisamp.aba 

In this example, the input list has three Tiles. RL5I links all the modules in each 
of these Files into the output Hie. (Note that the > > in the second line of the 
example is generated by the system in response to the continuation character & 
on the first line of the example.) 

3. > R U S 1 A : PROG 1 . OBJ (MODI, M0D3), A: PROG2.0BJ I 
>> (M0D2) TO A:PR0G3.ABS 

Here, the input list has two input files (PROG I. OBJ and PROG2.0BJ). From 
PROG I. OBJ. only the modules named MOD 1 and MOD3 are to be linked into 
the ouptut file; any other modules in file PROGI.OBJ are ignored by RL5I. 
From PROG2.0BJ, only the module named MOD2 is to be linked. 

4. >RL51 aiplmprg.obj, a : u t i 1 S 1 . 1 I b , aiioSl.ltb, » 

> > p 1 m 5 1 . 1 1 b 

The example introduces a typical linking using libraries. Here, plmprg.obj is linked 
with two private libraries and with the mandatory library plmSl.lib (which must 
be used if modules generated by plm5l participate in the linkage). 

5. > R L 5 1 Eiaapl ,ob] , cotrtg.lib, trig, lib, i' 

> > cotrtg.lib 

Interaction between libraries (i.e.. libraries that reference each other) may 
sometimes require the same library to be mentioned twice in the input list. 
In the preceding example, cotrtg.lib contains the COTANGENT and COSINE 
trigonometric functions, tng.lib contains the SIN and TANGENT functions, and 
exampl.obj references the COTANGENT function. 

Because COTANGENT equals l/TANGENT. trig lib must he specified to 
resolve the reference to the TANGENT function. Also, because TANGENT 
equals SINE/COSINE, cotrig.lib must be respecified to resolve the reference to 
the COSINE function. 



Output File 

The output filename is the name of the disk file that is to receive the absolute object 

module. 

If the output file name is omitted. RL51 creates a filename for the output file by 
removing the extension from the first filename in the input list and using the drive 
and root name only. If this input file contains no extension, a ratal error occurs. For 
example, the command: 

R L 5 I P R G I 

is illegal since the output filename defaults to PROGI. 

If there is alrcadv a file on the large! drive with the name of the output file. Ih.il file 
is overwritten b\ the new output file. 
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Examples 

Following are examples of RL5I oulpul file — 

1. > R L 5 1 a : p r o g . o b ) TO c : p r o g 

This example specifies file prog in directory c: as ihc oulpul file. 

2. > R L S 1 C :PR0G.QBJ 

This example uses the default output file generated by RL5I. The effect is the 
same as the first example; the output file becomes c:prog. 

3. > r 1 5 t aisamplel.ob], « : 1 up I ( ! . ob ) TO i 
>> c:\myflle\sampl.abs 

In this example, the output file is in a different directory than the input files, and 
the directory, filename SAMPL, and the extension .ABS are specified. 

Controls 

After the output filename, you can add a list of controls to select options for listing, 
linking, and locating the output. Use blanks (not commas) to separate controls in the 
list. The same control may not appear more than once in the list; if a duplicate control 
is encountered, a fatal error results and the program aborts. The next several sections 
explain the controls and give examples. 



Listing Controls 

The listing file output by RL51 can contain a link summary, a symbol table, an 
IXREF report, and a list of error messages. The link summary can contain a memory 
map of the linked segments. 

The listing controls are the PRINT option, the PAGEWIDTH control, the MAP 
option, the SYMBOLS option, the PUBLICS option, the LINES option, and the 
IXREF option. These controls allow you to specify the rile or device to receive the 
output listing, to omit the listing file altogether, to omit the map from the link 
summary, or to omit local symbols, public symbols, or line numbers from the symbol 
table. You may also specify if you wish to have the IXREF report generated, and the 
specific page width to be used. 

NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated without the DEBUG option, the SYMBOLS. PUBLICS, 
and LINES information will not be available for listing. 

PRINT/NOPRINT 

The print options control the destination of the list file. 

To direct the list file to a disk file, the print control format is 

PRINT ( I directory/device I tilename [ . exl ) ) 

Example 

> H L 5 1 a 9 a m p 1 t 1 . o b j I 
>> print (a:9ample.l!t) 
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To direct the lisi file to a device other than a disk file, the print control format is 

PRINT ( : device : ) 

where 

device is a device code. Common devices are CO (console), LP (line 

printer), TO (terminal other than console), and VO (video 
terminal screen). 

If you omit the print control, or if you enter the command word PRINT without a 
filename or device name, RL5I creates a disk file for the listing. The name of the 
default listing file has the same root as the output filename and has an extension of 
M5l; the drive number is also the one used in the output filename. 

Example 

> R L S T A : P R OG . BJ , A:PR0G1.0BJ TO B:PR0G2.ABS 

The output listing filename may not be the same as the output filename or any of the 
filenames in the input list. If the listing file duplicates an input or output filename, a 
fatal error results. If the listing filename already exists oh the target directory, the 
old file with that name is overwritten by the new listing file. 

The NOPRINT option specifies that no output listing file is to be produced 
NOPRINT overrides the MAP, SYMBOLS, PUBLICS. LINES and IXREF 

controls. 



PAGEWIDTH 

The PAGEWIDTH control specifies the maximum number of columns per line in 
the prinl output file. The control takes the form 

PAGEWI DTH( width ) 

where 

wid,h is an unsigned number which specifies the maximum page 

width to be used. 

The allowable range for width is 72 to 132. The default PAGEWIDTH is 78. 



Listing Switches 

The MAP. SYMBOLS, PUBLICS. LINES and IXREF controls select what portions 
of the listing files are to be generated. The default of any switch (with the exception 
of IXREF) is the positive form (MAP. SYMBOLS, PUBLICS, and LINES) 
Table 3-2 summarizes the listing switches. 

IXREF/NOIXREF 

This control specifies whether or not to produce the inter-module cross reference 
report. If IXREF is specified, the report is appended to the print file. 

A selection list may be added to the positive Form (only) of the IXREF control. A 
selection list causes RL5I to output or suppress output of various selected entries to 
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Table 3-2. Listing Switches 



Switch 


Etr.ci 


MAP 


Output memory map to link summary 


NOMAP 


Suppress memory map 


SYMBOLS 


Output local symbols to symbol table 


NOSYM80LS 


Suppress local symbols 


PUBLICS 


Oulpul public symbols to symbol lable 


NOPUBLICS 


Suppress public symbols 


LINES 


Output line numbers to symbol table (high-level language transla- 
tors only) 


NOLINES 


Suppress line numbers 


IXREF 


Append intermodule cross-relerence report to print file 


NOIXREF 


Suppress the intermodule cross-relerence report 



the IXREF report. An entry consists of a symbol and a module where this symbol is 
referenced (either as public or as external). The general form of the IXREF control 
is 

IXREF [ ( selection-item (,...])! 
where 

selection-item is either (NO)GENF.RATED or ( NO)LI BR AR I ES. If 
IXREF is specified and any of the selection items are omitted, 
the missing selection item assumes its positive form. A selec- 
, lion item may appear at most once. 

The selection-items are best explained by describing the effect of their negative form. 

The NOGENERATED control causes RL51 to surpress output of entries whose 
symbol name begins with a question mark (?); such symbols are usually PL/M-51 
generated symbols. The GENERATED form of the control causes RL51 to oulpul 
such entries also. 

The NOLIBRARIES control causes RLM to surpress output of entries whose module 
resides within a library. The LIBRARIES form or the control causes RL5I to include 
all libraries in the IXREF report. 

The selection list is used to control the number of entries collected for the IXREF 
report. This is needed when an excessive number of IXREF entries make it impossi- 
ble Tor RL51 to generate the IXREF report. 

Examples 

1. >RL51 a : p r o g . o b ] nosymbols nopubllca nollnes 

Because the default for any listing switch (except ixref) is the positive form, the 
main use of the switches is to suppress unwanted information. The invocation 
given in this example will suppress the entire symbol table. 

2. >r!51 aiprog.ob] print (aiprog.mSl) nomap nosb I 
> > noil 

In this example, only the public symbols wili tx printed ( no map or other symools 
or lines). Note the use of abbreviations (nosb for nosymbois and noli for nolines) 
to save keystrokes. A complete list of abbreviated forms appears at the end of 
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Chapter 3. Note that the blank separating print from its parameters is optional- 
you could also use print(a:prog.m5 1 ). 

3. > R L 5 1 a:prog.obj, eiprocs.obj, atplmSt.llb » 
>> liref(nogn) 

This example suppresses generated symbols from the ixref report. Using the nogn 
(regenerated) selection item prevents PL/M-51 run-time library procedures from 
being written to the ixref report. 



Linking Controls 

The linking controls allow you to name the resultant output module and (o specify 
which debug information is to be copied to the output module. 

NOTE 

In order to obtain the debug information (SYMBOLS. PUBLICS, or 
LINES), the DEBUG control must be included in the invocation line for the 
translator used to produce the input modules. 

NAME 

The NAME control allows you to name the output module. The format is 
NAME ( module-name ) 

If the NAME control is not used, the output module-name defaults to the name of 
the first input module processed. 

Example 

) R L 5 1 a : s s in p 11 . o b j , a : s a m p 1 2 . , b I TO a : s a m p 1 e . a b s I 
>> n a me C S AMP L E_P R G R A M ) 

In this example, the name SAMPLEJPROGRAM is assigned to the output module 
Note that the blank between NAME and its parameter is optional and can be omitted. 



Linking Switches 

The DEBUGSYMBOLS. DEBUGPUBLICS. and DEBUGLINES controls select 
wbat kinds or debug information are to be included in the oulpul Hie. The default of 
^ITHf? ' S a ' WayS the P0,itiv " form (DEBUGSYMBOLS, DEBUGPUBLICS and 
DEBUGLINES). Table 3-3 summarizes the linking switches. 

Examples 

I. >RL51 aiprogl.obj nodebugsymbols n o d e b u g 1 I n e s 

Because the linking switches default to the positive form, you will usually use the 
negative forms to suppress unwanted debug information in the output file. In this 
example, the output file contains only the information for the public symbols. 
> R I S 1 aiprogl.obj nodp nodi 

In this example. onU the local symbols are oulpul lo the absolule file Nole the 
use of abbreviations (nodp for nodebugpublics and nodi for nodebuglines). 
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Table 3-3. Linking Switches 



Switch 


Elltcl 


DEBUGSYMBOLS 

NODEBUGSYMBOIS 

DEBUGPUBLICS 

NODEBUGPUBUCS 

DEBUGLINES 

J NODSBUGLINES 


Copies local symbol Inlormation to outout lite 
Suppresses local symbols 
Copies public symbol information lo outout tile 
Suppresses public symbols 

Copies line number Intormation (high-level language translators 
only) to output tile 
Suppresses line numbers 



Locating Controls 

The locating controls allow you to assign absolute addresses to relocatable 

L ^c,rv the ordenng of relocatable segments of a given type ,n memory, and to 

force allocation of segments into a specific range or addresses. 

Allocation Sequence 

Th, .vstem allocates memory in accordance with segment attributes and locating 
5h- order It precedence. The precedence of the allocattng opera- 
lions (grouped by type of memory space) is as follows: 

Internal Data Space: 

. Absolute BIT, DATA, and IDATA segments, and register banks 
. Segments specified in a PRECEDE control in the RL5I command 
. Segments specified in a BIT control in the RL5I command 
. DATA type segments with relocation equal to BIT-ADDRESSABLE 

Other relocatable bit segments 
. Segments specified in a DATA control in the RL5I command 
. DATA type segments with relocation equal lo UNlT-aligned 
. Segmenls specified in an IDATA control in the RL5I command 
. Other relocatable IDATA segments, except ? STACK 
. Segments specified in a STACK control in the RL51 command 
. 7STACK, if it is IDATA and has not been specified in any other locate control 

External Data Space: 

Absolute external data segments 
. Segments specified in an XDATA control in the RL51 command 
. Other relocatable external data segmenls 

Code Space: 

Absolute code segments 
. Segments specified in a CODE control in the RL5I command 
. Other relocatable code segments 

NOTE 

In most cases, the allocation algorithm wij! produce ■J« i ^ M ^g! 
without requiring the user to enter any locating controls in he R 5 
command. These controls are inlended for the ^SmI c »« 
running RL5I without them does not g.ve a good enough result. 
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Format Summary 

The locating controls have the format 
control t segment [,...]) 
where 

segment : • segment-name t ( base-address ) ) 

The segments specified in the locating conlrols are allocated in the order Ihey appear; 
the first segment is assigned the lowest possible address, and succeeding segments 
receive higher and higher addresses. 

The user has the option of specifying the base address of any or all segments. Segments 
with specified base addresses must appear*in the list in ascending numerical order. 
Segments named in a locating control with i specific base address arc allocated at 
that address irrespective of segment overlap or segment type contradiction, as long as 
ascending order is maintained. Base addresses are byte addresses except for the BIT 
locating control, where addresses are bit addresses in the bit spaceO to 127). 

Table of Locating Controls 

Table 3-4 lists the locating controls in order of precedence. The first column gives 
the name of the control. The second column describes the address space affected by 
the control. The third column gives the address range for segments within each control. 
The last column shows what types of segmenls are allowed for each control: for each 
valid type, the column also shows the allowable relocation aitributcs. (Refer to the 
MCS-51 Macro Assembler User's Guide and PL/M-51 User's Guide for details on 
segment types and relocation attributes.) 

Notes On Locating Controls 

The following notes refer to table 3-4. 

I. Bit addresses for non-BIT segments in the BIT control must be on byte bounda- 
ries; that is. they must be divisible by eight. (BIT-type segments can be aligned 
on bit boundaries.) 



Table 3-4. Locating Controls 



Control 


Addrats Space 


Addreai Range 

(Max) 


Segment Typei 
(and Attribute!) 


PRECEDE 


Register banks and bit- 
addressable space in 
on-chip data RAM 


00H-2FH 


DATA (UNIT-aligned); 
IDATA , 


BIT 


Bit-addressable space 
In on-chip data RAM 


00H - 7FH 
(see note 1) 


BIT; DATA; IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


00H - 7FH 


DATA (UNIT-aligned); 
IDATA 


IDATA 


Indirectly-addressable 
on-chip data RAM 


OOH - OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 

nole 3) 


Same as IDATA 


Same as IDATA 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 
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2. The range of addresses for Ihc I DATA control is tlcpcmlcnl nn Ihe large! machine. 
See Ihe RAMSIZE control later in this chapter. 

3. The STACK control specifies which segments are 10 he allocated uppermost in 
the IDATA space. The memory accessed starts afier the highest on-chip RAM 
address occupied by any previously allocated segment and continues to the top 
of the IDATA space. 

NOTE 

This control has no other effect on any segments. 

The IDATA 7STACK segment, if il exists, is placed higher than segments 
that were mentioned in the STACK control. 

The STACK control provides a convenient way to handle Ihe stack (usually for 
ASM5l-based application, where 7STACK is not used). 

First, assign the stack pointer (SP) (o a relocatable segment: consider the following 
ASM.M example: 

STACK_A»EA SEGMENT IDATA j SEGMENT directive in uulci. 

D5 UN r»i l( tytii lit itnl. 

^ 1 Other CODE i rutrucllonl. 

MOV SP, 'STACK_A«EA- 1 ; I r, I t I a I l I e SP. 

Then, at relocation time, specify the segment named STACK^AREA in a STACK 
locating control: 

R L 5 1 ... STACK ( ST ACK_ARE A ) 
where 

ellipsis (...) represents the rest of the invocation line exclusive of the 

STACK control. 

NOTE 

If the application contains modules produced by PL/M-51, the 7STACK 
should be used as the slack segment. 

Examples 

1. > R L S 1 ArPROOl .OBJ, A:PR0G2.0BJ TO AiPROG.ABS t 
>> PRECEDE (MESSAGE 1 ) XDATA (ARRAY1 ( 2 5 6 ), I 

> > ARRAYS (512)) 

In this example, the DATA (or IDATA) segment names MESSACEI will be 
allocated space in on-chip RAM in the lowest available location, overlapping the 
BIT space if necessary. The XDATA control specifies that the two arrays are to 
be located at specific addresses (e.g., for debugging). 

2. > R L 5 1 A: TEST. OB J STACK (STACK _A R E A ) 

Here, the STACK control allocates the uppermost portion of IDATA space for 
the segment named STACK_AREA. 

3. > R L S 1 APROO.OBJ, B P R . B J , P L M 5 1 .LIB » 
>> CODE (MODI MOOOH), M0D2, MODS) 

Here, the CODE control allocates space in code memorv for segments MODI, 
MOD2. and MOD.V MODI is aligned at location 400011. MOD2 and M0D3 
are assigned contiguous addresses after MODI. 
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Configuration Controls 

The configuration controls are used to describe (he actual configurations that objects 
are aimed to. 

This group contains the RAMSIZE control. 



RAMSIZE 

The RAMSIZE control format 

RAMSIZE lvalue) 

where 

value is a number in the range 1 28 to 255. 

RAMSIZE specifies the maximum amount of on-chip RAM that may be allocated 
for the user program. The default value for RAMSIZE is 128 (as is the case for the 
8051). IT the object is aimed at more than one configuration of the MCS-51 family, 
specify the MINIMUM of all on-chip RAM sizes among all machines you want to 
link. 

The sole use of this control is to enable RL51 to check on-chip memory size constraints 
at RL-time and thus avoid confusion at ICE-time. 



OVERLAY/NOOVERLAY Controls 

The linker allows overlaying of on-chip RAM segments among modules, under the 
specification or the OVERLAY control. Two segments can be overlaid if all the 
following conditions exist: 

• The segments have the same type (DATA, IDATA, BIT, or 
BITADDRESSABLE). 

• The segments use the same register bank (determined by the USING attribute 
or the REGISTERBANK control). 

• The segments are marked as overlayahle. Currentlv, this is done only by the 
PL/M-51 compiler. ASMS I (V2.1 and lower) lacks this feature. Therefore, 
assembler segments are considered non-overlayable. 

• The segments belong to disjoint modules. That is, no procedure in one module 
can directly or indirectly call a procedure from the other. 

The default is NOOVERLAY. No overlaying of on-chip RAM segments is done by 
the linker. 

The general form of the OVERLAY control is as follows: 

OVERLAY [ ( overlay-unit (,...))) 

where 

overlay-unit is ov-module-name calls ov-module-name. 

ov-module-name is a legal RL5I module name or * which stands for all the 
module names. 

calls is > or 1. 
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OVERLAY 

If the OVERLAY control appears in the invocation line without arguments, the linker 
assumes thai no intra-module calls exist except for those deducible from the PUBLIC- 
EXTERNAL declarations, and that overlaying of all overlayable segments is safe. 



NOOVERLAY 

The linker does not overlay data segments. 



OVERLAY (A > B) or (A 3 B) 

If the OVERLAY control appears in the invocation line with arguments, it indicates 
that there are invisible calls between modules. In the OVERLAY control syntax, 
either the greater than sign ( > ), or the right square bracket ( ] ) may be used in the 
calls relationship. The greater than sign will be used in the text. The notation A > B 
means that module A calls module B. In this case, the linker overlays all overlayable 
segments, except that segments from A are not overlaid by segments from B. Note 
that the added connection can prevent other segments from overlaying. For example, 
if the segment A was overlaid with the segment D, and B calls D (visibly by PUBLIC- 
EXTERNAL declarations), then the effect of A > B is that A and D will not be 
overlaid, since A can call D through B. 

OVERLAY (A > *, * > B) or (A ] 7 ] B) 

A module can be declared as non-overlayable in two ways. The argument A > * 
indicates that the module A calls all other modules. On the other hand, ' > A means 
every module calls A. In either case, no segments from A will be overlaid. The effect 
of each form depends on the nature of A. For example, if the * > A form is used and 
A visibly calls all other modules, then every module can call (through A) each other 
module. In this case, the linker will not perform any overlays. 

The overlaying or data segments in on-chip RAM has the following restrictions: 
The OVERLAY control cannot be invoked with the IXREF selection items 
NOGENERATED or NOLIBRARIES. RL5I generates an error if either one 
is specified. 

• Combined segments and segments appearing in locating controls are not overlaid 
by the linker. 

Following is an example in which two disjoint modules share the same on-chip RAM 
area: 

m o d 1 i DO; 

T H R E E_9 EARS: PROCEDURE PUBLIC; 

DECLARE L I TTLE BEARS BED BYTE ; 

IF BOOLEAN C L I TTLE_BE A RS_BED ) THEN 

CALL MSG (.(' SOME ONE '' S BEEN IN MY BED! ' ) , ) 

L I TTLE BEAR S_B ED • ; 

END T H R E E_B EARS; 

END m o d 1 ; 
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mod2 : DO ; 

GOLDILOCKS: PROCEDURE PUBLIC; 

DECLARE SPAR E_B E D BYTE ; 

SPARE BED • I; 

END GOLDILOCKS; 

END mod2 j 

«il»_itiiry: DO; 

THREE_BEARS: PROCEDURE EXTERNAL; END; 
GOLDILOCKS: PROCEDURE EXTERNAL; END; 

CALL THREE_BEARS ; 
CALL GOLDILOCKS; 
CALL T H R £ E_B EARS; 

END ill 1 n_i I ory ; 

In this example, the linker reserves the right to use the LITTLE_BEARS_BED as a 
SPARE_BED because the two procedures are never active simultaneously. 

To perform overlaying, the linker must determine which procedures are active simul- 
taneously. To do this, the linker assumes that all CALLs can be executed. For example 
if procedure A calls procedure B, and B calls procedures C and D, then the linker 
can overlay RAM variables from C only with the RAM variables of D. 

The linker, however, looks only at the PUBLIC-EXTERNAL declarations. It assumes 
that any reference to an EXTERNAL procedure will be executed, but ignores the 
possibility of hidden calls. The arguments to the OVERLAY control are therefore 
needed to specify those interconnections between modules that cannot otherwise be 
detected by the linker. 

Such situations arise if the interconnection is done by a computed call to an external 
procedure whose address is not determined by a simple PUBLIC-EXTERNAL 
relationship. For example, module A imports from module B a public variable that 
contains the address of a local or public procedure in B. Module A then performs a 
computed call to the procedure in B. The rule can be stated as follows: The linker 
assumes a connection from module A to module B if there exists an external refer- 
ence m A to a public procedure in B. In all other cases, hidden connections must be 
explicitly given as arguments to the OVERLAY control. 

Following is an example of a computed call to an external procedure: 
MODI: DO ; 

DECLARE l_0_CLEAR WORD EXTERNAL ; 

CALL I_0_CLEAR; 



END MOD) 
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In another module, you have: 

M0D2 : DO ; 

DECLARE l_0_CLEAR WORD PUBLIC; 

READER : PROCEDURE; 

l_0_ERROR : PROCEDURE ; 

E N D I _ _ E R R R ; 

I_0_5UCCE5S: PROCEDURE; 

END I_0_SUCCESS; 

IF ERR_C0DE <> 

THEN l_0_CLEAR • . I _0_E R R R ; 
ELSE l_0_CLEAR ■ . I SUCCESS ; 



END READER ; 
END M0D2; 

In the above procedure, MODI invokes a procedure defined in MOD2. To prevent 
the linker from overlaying on-chip RAM variables of MOD2 with on-chip RAM 
variables of MODI, the following form of the OVERLAY control must be used: 

OVERLAY (MODI > K0D2) 

Overlaying can be a good way of economizing on-chip RAM space; however, overlay- 
ing may, in some cases, give worse results. For example, if most procedures call one 
another, the resulting segments will expand, making it more difficult for the linker to 
allocate a few large segments than many small ones. 

The outcome of the overlaying process can be checked by inspecting the link map. 
All overlaid segments are indicated by "OVERLAP**. Warning (4), DATA SPACE 
MEMORY OVERLAP, is not generated for those segments. 



Abbreviations for Command Words 

Most of the command words in the RL5I command have short forms to save you 
keystrokes over the full spellings. Here is a list of the command words and their 
abbreviations. 

Command Word Abbrevinlion 



BIT 


BI 


CODE 


CO 


DATA 


DT 


DEBUGLINES 


DL 


DEBUGPUBLICS 


DP 


DEBUGSYMBOLS 


DS 


GENERATED 


GN 


IDATA 


ID 


IXREF 


IX 


LIBRARIES 


LB 
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LINES 


LI 


MAP 


\A A 

MA 


NAME 


XT A 

IN A 


NODEBUGLINES 


rNUUL 


NODEBUGPIIRI rrs 


NODP 


NODEBUGSYMBOLS 


[NUUo 


NOGENERATFD 


NOGN 


NOIXREF 


Mn r v 


NOLIBRARIES 


INULB 


NOLINES 


NOLI 


NOMAP 


NUMA 


NOOVERLAY 


NOOL 


NOPRINT 


NOPR 


NOPUBLICS 


NOPL 


NOSYMBOLS 


NOSB 


OVERLAY 


OL 


PAGEWIDTH 


PW 


PRECEDE 


PC 


PRINT 


PR 


PUBLICS 


PL 


RAMSIZE 


RS 



RL51 Outputs 




The RL51 program produces three outputs: console displays, a listing file, and the 
abi dte object module file. This chapter describes these outputs and gives examples. 
As discussed in Chapter 3, the listing controls in the RL5I command allow the user 
to suppress some information in the listing Tile, and the linking controls can suppress 
some information in the absolute object Tile. 



Console Display 

The console displays produced by RL5I consist of a sign-on message and any error 
messages that occur. The sign-on is as follows: 

system-id M C 5 - 5 I RE LOCATOR AND LINKER Vx.y 

where 

x y is the version number. 



Listing File 

RL5I produces a listing file unless it is suppressed in the RL5I invocation. The RL5I 
listing file contains: 

* A summary of the link and locate process 

• A symbol table, as specified in the RL51 invocation 
An inter-module cross-reference listing (IXREF) 
Error messages detected by RL51 



Link Summary 

A sample of a link summary is shown in figure 4-1. The summary includes the follow- 
ing kinds of information: 

• A header echoing the RL51 invocation. 

Input modules included in the link process. Input modules are identified by module 
name and file name. 

• A link map (unless suppressed by the NOMAP control). The map lists all 
allocated segments, giving the type, base address, and length of each segment. 
The map also identifies segment overlaps and gaps in the memory space. 

A list of segments that were ignored in the link process. If any segments were 
ignored, the reasons for doing so will be reported later as an error. 

A list of unresolved external symbols. An external symbol is unresolved when it 
is not matched by a public symbol in one of the input modules. Each occurrence 
of an unresolved external symbol in a module will be reported later as an error. 
A list of all symbols that were ignored in the locale process. A symbol is ignored 
when the same name appears as a public symbol in different modules, or has 
attributes that are incompatible with external references, or belongs to an ignored 
segment. Each occurrence of an ignored symbol in a module will be reported 
later as an error. 
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R L S t F 1 L E 1 . E X T ( M D 1 , M D 2 ) , F 1 L E 2 . E I T 
NAME (EXAMPLE) MAP PRINT CltMJ 

INPUT MODULES INCLUDED 
F ILE 1 .EXT(MODI) 
FILE1.EXTCMOD2) 
FILE2.EXTCMDD3) 



LINK MAP FOR OUTFIL. 


EXTCEXAMPLE) 






TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT NAME 


REG- 


H 


8 H 




"REG BANK 0" 
D A T A_S E G_ 1 




8 H 


1 H 


UNIT 




DATA 


H H 


8 H 


ABSOLUTE 


"REG BANK 3" 


DATA 


1 B H 


8 H 






• ■OVERLAP" REG 

B 1 T 


2 H 


1 H . 5 


UNIT 


A_B I T_S E G 
■••GAP''' 




2 1 H . 6 


H , 2 




D A T A_S E G_2 




2 2 H 


1 H 


B 1 TADDR 




DATA 


2 3 H 


B H 


ABSOLUTE 




DATA 


2 EH 


0042H 


UH 1 T 


5 T A C K_S E G 
. • • AP • 1 * 


1 DATA 


7 OH 


1 H 






XDATA 


H 


C OH 


UNIT 


DYHAMI C_MEM 




H 


1 3 8 9 H 


UNIT 


PROC 1 


CODE 


1 3B9H 


4 7 7 H 




• • 'GAP ' ' ' 


CODE 


1 8 H 


7A5H 


1 NBLOCK 


PROC2 



IGNORED SEGMENTS 
DYNAMIC POOL 

UNRESOLVED EXTERNAL SYMBOLS 
INVERT 

IGNORED SYMBOLS 
B 1 T 2 5 6 



Figure 4-1. Link Summary 



NOTE 

will produce additional error messages. 



Symbol Table 

s boss: imtzzvff&stvtt 

figure 4-2. 
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SYMBOL TABLE FOR 


OUTF 1 LE . EXT(EXAMPLE) 




VALUE 


TYPE 
.... 


y i Ml 
M A n L 




MODULE 


M t M R Y 


f\ ft ft ^ ^ II 

D : 3 2 H 


PUBLIC 


i n u m r u o T o 
L U H_fl i n_P T R 


T1 - ft ft 1 A LI 

B : 2 H 


n ii n i \ f> 

PU BL 1 C 


I H 1 T — f LAG 


n ft ft t a l r i 

8 : 2 H . 1 


n ii n 1 J i"i 

PUBLIC 


riii i r i at 
F UL L_ .r L A v 


D : 3 4 H 


n II n i if* 

PUBLIC 


u t r u m r m o 7 o 


V ft ft ft ft 11 

X : H 


a It n | 1 

PUBLIC 


n v w a m i r m r w n d v 




PROC 


A 1 1 fl !• A T f 

ALLOCATE 


IS ft ft A H 

D : 5 4 H 


SYMBOL 


u ii w n v t r r 

M U n_B TIES 


D : 6 8 H 


SYMBOL 


PDOl SELECTOR 


D : G 8 H 


SYMBOL 


A L L C_P T R 


B : 2 H . 2 


SYMBOL 


FLAG 


C : H 


LINE' 


1 9 


C : 7 H 


LINE' 


2 


C : 1 H 


LINE' 


2 1 


C : 1 3 H 


LINE' 


2 2 




DO 




D : 6 A H 


SYMBOL 


1 


C : 1 8H 


LINE' 


2 3 


C : 2 1 H 


LINE' 


2 4 


C : 2 8 H 


LINE' 


2 5 


C : 2 F H 


LINE' 


2 G 


C : 3 2 H 


LINE' 


2 7 




E N D D 


■ 


f . ft i -i 1 i i 

C 1 3 7 H 


LINE' 


2 8 


1* a ft n A f> u 

C : 4 H 


LINE' 


o a 

Z 3 


^ ft n j r u 


LINE' 


3 


C : S 7 H 


LINE' 


3 1 


C : 5 F H 


LINE' 


3 2 


C : 6 8 H 


LINE' 


33 


C : GFH 


LINE' 


3 4 


C : 7 GH 


LINE' 


35 1 


C : 8 2 H 


LINE' 


36 


C : BFH 


LINE' 


3 7 


C : 9 4H 


1 1 NE ' 


38 




E N DP R C 


ALLOCATE 




ENDMOD 


MEMRY 



Figure 4-2. Symbol Teble 



NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated wilhout the DEBUG option, the SYMBOLS. PUBLICS, 
and LINES information will not be available for listing. 



The symbol table contains scope definitions and information about the symbols and 
line numbers. Scope definition identifies the module. DO block or procedure that 
contains the symbol or line number. Note that when the table contains only public 
symbols (i.e.. NOSYMBOLS and NOLINES controls are in effect), scope definition 
is by module only. 
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Each entry in tU .able census of three part,. » Wte** 

. VALUE. The value is the absolute ^.^^^^TiZ I 
With a Idler indicating the type of add™" 1 ^ , eH number) . A byte 

indirect internal data; B. b, £ ^our-dig.t hexadecimal 

address (or a bit address on a W'^'^urite* •„ is on . byte boundary) is 

zzirssrj^^ fitsas - * ° ffset « ,hrough 7) 

m^ype Held identifies the entry as a local symbol (SYMBOL), a public 
" v, i 7pi inffc) segment (SEGMENT), or a line number (L1NE#). 

For sc0P e definition, a line PROC for WOCEDUm 

Ir^ P threnVor each'block °(EN rjMO^ ENDr)0. EN DPROC). The NAME Held 
shows the name of the block, if any. 



NOTE 

SBawsSaSrtssftsass 

(e.g., PL/M-51). 



Inter-Module Cross-Reference Report (IXREF) 

figure 4-3. 

The IXREF report consists of ^^^££j^^t 

co^esindmg address ^t^^* red VuBUC or EXTERNAL. 
Marts a list of modules Itl which : ^*^ , vmbo , W|S declared PUBLIC. 

The first module name in the list i S and the NOLIBRAR- 

l( a symbol ,s WW"***' •fl^W-dtlin ^^raOLVED " appears in front 
IES selection item is in effect, then the string 
of the modules list. 



Error Messages 

R L5 1 disp,ys error messages on the console and cop.es them to the end of the listing 
file unless the listing file is suppressed. 

RL51 error messages ^^^S^^^^ 
detected condition that may or may not be -ha i w lerminale oper alion, but 

operalion of RL5I . 



Refer to Appendix B for a Us, of the error mess es and probable causes. 
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INTER-MODULE CROSS-REFERENCE LISTING 



NAME USAGE MODULE NAMES 



7 C H E C K_E Q 7 B Y T E . . , DATA; CHKEQ TESBAS 

'CHECK_EQ_BITS'BIT. BIT; CHKEQ 

' P 8 CODE; ? P 8 TESBAS 

? P 1 S CODE; ' P 1 5 TESBAS 

? P 1 6 CODE; ' P 1 S TESBAS 

7 P I H R CODE; TESBAS 7 P I V R 

if 1 VO R CODE ; ' P IVOR TESBAS 

7 PSWO R NUMB; TESBAS ' P I VOR 

C H E C K E Q CODE; CHKEQ TESBAS 

CHECK EQ BITS . . . CODE; CHKEQ 

CHE CK_E X1T CODE; CHKEQ 

CHE CK_I NIT CODE; CHKEQ 

PUBOO CODE; MODULE_0 M0DULE_1 M0DULE_2 

PUBOt CODE; MODULE_0 MODULE_l M0DULE_2 

PUB02 CODE; MODULE_0 M D U L E_ 1 M0DULE_2 

PUB03 CODE; •• UNRESOLVED •• MODULE_, H0DULE_2 

P U B 4 CODE; MODULE_0 MODULE 1 M0DULE_2 

PUB05 CODE; MODULE_0 M0DULE_1 M0DULE_2 

PUB06 CODE; •' UNRESOLVED »• MODULE_l M0DULE_2 

PUB07 CODE; MODULE_0 M □ D U L E_ 1 M0DULE_2 

PUBOB CODE; MODULE_0 MODULE 1 M0DULE_2 

PUB09 CODE; MODULE_0 M D U L E_ 1 M0DULE_2 

PUBtO CODE; MO DUL E_t) 

PUBIt XDATA; MODUL E_0 

PUBI2 DATA; MODULE_0 

PUB, 3 I D A T A ; M D U L E _ 

PUBM . . . . . . . BIT; MODUL E_0 

PUB ,5 NUMB ; MODULE_0 

PUBIS CODE; MODUL E_0 

PUB17 CODE; MODULE_0 

PUB18 CODE; MODULE_0 

PUB, 9 CODE; MODULE_0 

PUBXO CODE; M D U L E_ , MODULE_0 

PUBX, CODE; M D U L E_ , MODULE_0 

PUBYO CODE; •• UNRESOLVED " M D U L E_ , M0DULE_2 

PUBZO CODE; '• UNRESOLVED M D U L E_ , 



Figure 4-3. IXREF Lifting 

Absolute Object File 

The linking and locating process combines one or more relocatable object files into 
one absolute object file. The absolute object file contains one module; the absolute 
module consists of 

• A module header record that identifies the module. 

• A set of iniermixed content and debug records. The content records contain the 
program code. The debug records contain the location and scope of local symbols, 
public symbols, segment symbols, and line numbers, as specified by the DEBUG- 
SYMBOLS. DEBUGPUBLICS, and DEBUGLINES controls in the RL5I 

invocation. 

A module end record that verifies the module name. 



Examples of Program Development 



This chapter shows three brief examples of program development using ASM5I, 
PL/M-51, and RL5I. The first example is tne sample program discussed in the 
ASM51 User's Guide: the example shows how to assemble each of the three modules, 
then link and locale them into a single absolute object module with RL5I. The second 
example is a short program that illustrates the use of the locating controls. The third 
example shows the use of RL51 with PL/M-51 modules, emphasizing the library 
process. 



Using Multiple Modules 

The first example is a program of three modules, named SAMPLE. CONSOLE^ 10. 
and NUM_CON VERSION. The source for these modules is in three files, 
SAMP1.A5I. SAMP2.A5 1 , and SAMP3.A5 1 , respectively. To assemble these 
modules, invoke the assembler as follows: 

ASMS 1 SAMP I . AS t DEBUG 

ASMS 1 S A M P 2 . A 5 1 DEBUG 

ASMS I SAMP3 . A 5 1 DEBUG 

Note that this example assumes the three source Tiles are on the same directory or 
device as the assembler and linker/locator, and that the output file will be sent to the 
same directory or device. The assembler invocations use the DEBUG control to have 
the symbol tables output to the object files for the three modules. 

After assemblv is complete, the system has created object files SAMPI.OBJ. 
SAMP2.0BJ, and SAMP3.0BJ, and listing files SAMPI.LST. SAMP2.LST and 
SAMP3.LST. The three listing Tiles are shown in figures 5-1, 5-2, and 5-3. 

To link and locate the three modules, enter the command 

RLS1 SAMPI.OBJ, SAMP?. OBJ, SAMP3.0BJ I 
• 'TO SAMPLE I 

••PRINT (SAMPLE. 1ST) SYMBOLS LINES PUBLICS 

After the RL51 program has executed, the system has placed the absolute object 
module in file SAMPLE, and an output Tile with information on the link and locate 
process in File SAMPLE. LST. The output Tile also contains symbol table information 
as requested by the SYMBOLS, LINES, and PUBLICS controls. The listing file is 
shown in figures 5-1 through 5-3; figure 5-4 shows the output file. 



MCS-S1 MACRO ASSEMBLER SAMPLE 
system-id N C S - S 1 MACRO ASSEMBLER Vx.y 
OBJECT MODULE PLACED IN SAMP1.0BJ 
ASSEMBLER INVOKED BY: A S M 5 1 SAMP) 



A 5 1 DEBUG 



IOC 


OBJ 


LINE 


SOURCE 










1 


NAME SAMPLE 










2 
3 


E X T R N co 


de (pu t_c r 1 f , put_strlng, 


p u t _d a t a_s t r ) 






4 


EXTRN code (get_num, blnau , licbln) 







5 
6 


C S E G 










7 


; Thl! 13 the Initializing section. 


Execution 






8 


; always i lir l! at address on power-up. 







9 


ORG 









758320 


1 


MOV T M D , ' 1 B ; Set timer to 


auto-reload 


3 


7S8D0 3 


1 t 


MOV TH 1 , ' ( 


-253) i Set timer for 110 BAUD 


6 


7 5 9 8 DA 


1 2 


MOV SCON , all 1 ( 1 11 1 0B ; Prepare the 


Serial Port 


9 


D28E 


1 3 
1 4 


SE IB TR 1 


; Start c 1 o c 1 








1 5 


; This Is the main program. It's an 


Infinite loop, 






i e 


; where each Iteration prompts the console for 2 






1 7 


; Input nun 


hers and types out their 


sum. 






1 8 


START : 










1 9 


; Type mess 


age explaining how to cor 


rect a typo 


B 


9 F 


2 


MOV DPTR,' 


t y p o_m s g 




E 


12 F 


2 1 


CALL put_st 


ring 




11 


12 F 


2 2 


CALL put_cr 


1 f 








2 3 


i Get first 


number from console 




14 


900000 F 


2 4 


MOV DPTR,' 


n u m 1 _m s g 




17 


12 F 


25 


CALL pu t_s t 


ring 




1 A 


12 F 


26 


CALL pul_cr 


1 f 




1 D 


7 8 F 


2 7 


MOV R ' n urn 


t 




1 F 


120000 F 


2 8 


CALL get_nu 


m 




0022 


120000 F 


29 


CALL put_cr 


1 f 








30 


; Get second number from console 




2 S 


900000 F 


3 1 


MOV DPTR,' 


nun 2_m s g 




2 8 


120000 F 


3 2 


CALL pu t_s t 


ring 




2 B 


12 F 


3 3 


CALL put„cr 


1 f 




2 E 


7 8 F 


3 4 


MOV R0,»num2 






120000 F 


35 


CALL g e t_n u m 





Figure 5-1. SAMP 1 Listing File 



3 3 12 



3 6 
3 8 
3 B 
3 D 

4 
4 2 
4 4 

4 6 
4 8 

4 B 
4 E 
5 1 
5 3 
00S5 
5 8 



8 




4 
8 



7 9 
12 
7 9 
12 

£500 
2 5 
F 5 

7 9 
12 

900000 
12 
79 
7A04 
12 
BOB 1 




4 
8 
C 
10 
till 
18 
00 1A 



5459S04S 
205ES820 
544F2052 
4SS4S950 
4 S 2 4 1 2 
4ESS4D42 
4 5 5 2 




36 

3 7 
38 
39 

4 
4 1 
4 2 
4 3 
4 4 
4 5 
4 6 
4 7 
4 8 
4 9 
50 



CALL put_crlf 



Convert the ASCII number , to b I nary 
MOV R 1 , / num 1 ' 
CALL ascbln 
MOV R 1 , * n u m 2 
CALL ascbln 

MoJ^a'nu'ml n ' I "' b^r, • and ,tort th5 results In SUM 
ADD a , n u m 2 
MOV s u m , a 

I Convert SUM from binary to ASCII 
MOV R 1 , ' s u m 
CALL b I na s c 

1 Output sum to console 
MOV DPTR. /s„m „.„ 



5 1 


CALL 


p u t_s I r l 


— 3 

ng 


52 


MOV 


R 1 , ' 3 u m 


S 3 


MOV 


R2 , '4 




S 4 


CALL 


p u t _d a t a 


_3 t r 


5 5 


JMP 


start 




56 






5 7 


DSEG at 8 




58 


STACK : DS 8 




59 








6 








6 1 


DATA. 


.AREA 


s e g m 


6 2 
63 


C0NSTANT_AREA 


s e g m 


64 


RSEG 


d a t a_a r e a 


65 


N U M 1 : 


DS 4 




66 


NUM2 : 


OS 4 




67 


SUM: 


OS 4 




68 








69 
70 


RSEG 
TYPO_ 


constant 
MSG: OB • 


_a r e i 
TYPE 



At power-up the st.c. pointer I, 
initialized to point her e . 



Figure 5-1. SAMP 1 U.tlng File (Cont'd.) 



t B 


S4S9504S 






7 t 


NUM I 


_M 5 G : D B 


"TYPE IN FIRST NUMBER- 


' , H 


1 F 


2 4 9 4 E 2 
















3 3 


4 6 4 9 S 2 5 3 
















2 7 


54204E55 
















25 


4D4245S2 
















2 F 


3A20 
















3 1 



















3 2 


S459S045 






72 


N U M 2 


_M S G : D B 


•TYPE IN SECOND NUMBER 


' , H 


3 S 


2 4 9 4 E 2 
















3 A 


S34S434F 
















3 E 


4E44204E 
















4 2 


S54D4245 
















4 s 


S23A20 
















4 9 



















4 A 


S 4 4 8 4 S 20 






7 3 


SUM_ 


MSG: D8 


'THE SUM IS ' , 00H 




4 E 


S3S54D20 
















5 2 


495320 
















5 5 



























74 


















7 5 


END 








SYMBOL TABLE 


LISTING 












N A 


M E 


T 


Y P E 




V A L U 


E 


ATTRIBUTES 




ASCB 


IN. . . . 


C 


A D D R 




_ 


E X T 






B 1 N A S C . . . . 


C 


A D R 







EXT 






C Q N 5 T A N T__A R E A 


c 


SEG 




5 G H 




R E L • UN I T 




DATA 


_A R E A . . 


D 


SEG 




C H 




REL -UN I T 




GET_ 


HUM . . . 


C 


ADDR 






EXT 






NUM 1 


_MSG. . . 


C 


ADDR 




1 BH 


R 


SEG-CONSTAHT_AREA 




N U M 1 




D 


ADDR 




H 


R 


SEG-DATA_AREA 




H U M 2 


_NSG. . . 


C 


ADDR 




3 2 H 


R 


SEG-CONSTANT^AREA 




NUM2 




D 


ADDR 




4 H 


R 


S E G - D A T A_A R E A 


PU T_ 


CRLF . . . 


C 


ADDR 






EXT 




P U T_ 


DAT A_S T R . 


C 


ADDR 






E X T 




PUT_ 


STRING. . 


c 


ADDR 






EXT 






SAMPLE . . . . 
















SCON 




D 


ADDR 




9 8 H 


A 






STACK . . . . 


D 


ADDR 




8 H 


A 




START . . . . 


C 


ADDR 




OOOBH 


A 





Figure 5-1. SAMP 1 Lifting File (Cont'd.) 



SUM_MSG c 

SUM • • • .' '. D 

TH ' D 

TMOD. . 

T R 1 g 

TYPO_MSG. . c 
REGISTER 8ANKCS) 
ASSEMBLY COMPLETE 



ADDR 


4 A H 


ADDR 


8 H 


ADDR 


8 D H 


ADDR 


8 9 H 


ADDR 


8 8 H . 6 


ADDR 


H 


USED : 


. TARGET 



SEG' 
SET- 



C N S T A N T_A R E A 
DATA_AREA 



SEG-CONSTANT_AREA 



MACHINE(S) 
NO ERRORS FOUND 



8 5 1 



system-id M C S - S 1 


MACRO ASSEMBLER Vx.y 


OBJECT NODULE 


PLACED IN SAMP2.0BJ 


ASSEMBLER INVOKED BY: ASMS 1 


SAMP2.A51 DEBUG 


LOC 


OBJ 


LINE 


SOURCE 






1 


NAME C Q N S Q I E_ I Q 






2 
3 


• 

[Q_RQUTINES segment CQOE 






4 


RSEG IQ_RQUTINE5 






S 


; This 15 the console 10 routine c lul te> . 






6 


PUBLIC put„crlf, put_strtng,put _d ata_str,get_num 






7 
8 


USING 






9 


: 

; This routine outputs a Carriage Return and 






1 


; a Line Feed 






1 1 


P U T_C R L F : 


D 


1 2 


CREQU ODH ; carriage return 


A 


1 3 


LFEQU 0AH jllnefeed 






1 4 


1 





7 4 D 


1 S 


MOV A , ' c r 


2 


12 


F 1 6 


CALL put_char 


S 


7 4 A 


1 7 


MOV A , ' 1 f 


7 


12 


F 1 8 


CALLput_char 


A 


2 2 


1 9 


RET 






20 


! 






2 1 


; Routine outputs a null-terminated string located 






2 2 


; In CODE memory, whose address Is given In DPTR. 






2 3 


PU T_S T R I NG : 


B 


E4 


2 4 


CLR A 


c 


93 


2S 


MOVC A , « A • D P T R 


D 


6 6 


26 


J Z exit 


Iter 


12 


F 27 


CALL p u t_c h a r 


! 2 


A3 


28 


INC DPTR 


t 3 


80F6 


29 


JMP put_strlng 






30 


EXIT: 


1 S 


2 2 


3 1 


RET 






32 


1 






33 


; Routine outputs a string located In DATA memory. 






3 4 


; whose address Is in R1 and its length In R2. 






35 


P U T _ D A T A _ S T R : 



Figure 5-2. SAMP2 Li. ling Flla 



16 E 7 

17 12 

1 A 9 

1 B DAF9 

1 D 2 2 



1 E 
2 1 
2 3 
2 S 



3099FO 
C299 
F 599 
22 



2 6 7 A 4 
0028 A900 

002A 120000 



2 D 
2 F 
3 2 
3 5 



C2E7 
B4 180S 
12 
80EF 



3 7 F 7 

3 8 9 

0039 DAEF 

3 8 2 2 



36 

3 7 
38 
39 

4 



4 2 
4 3 
4 4 

4 5 
4 6 
4 7 
4 8 

4 9 

5 
S 1 
5 2 
53 
5 4 
S 5 
56 

5 7 
58 
59 

6 
6 I 
62 
63 

6 4 
65 
66 
67 
68 
69 

7 
7 1 
72 



MOV A , «R 1 

CALL p u t_c b a r 
INC R 1 

JNZ R2 , pu t_da t a s t r 
RET 

I >"U-« output, . ,.„,,, character (Q con , olf 

•The character 1, gi vtn t „ „ 

PUT_CHAR: 

JNB T I , I 

CLR T I 

MOV SBUF , A 

re r 

Get a 4 character string from console 

"d , ore, i, at t h. address given In R0. 
GET^NUM '•"»"•'. r0uU " e -v., again. 

«o°v m'aW : ll l u f " rl "9 '"9 th - « 

GET_L00P: ' be " ecded ' • ' restart 



CALL g e t_c h a r 
I Next 4 lnstr's handle 
; over if received 
CLR ACC . 7 
C JNE A , / 1 8H , G0_0N 
CALL pu t_cr 1 f 
JMP ge t_num 

G0_0N : 

MOV »R I , A 
INC R 1 

DJNZ R2 , ge t_l oop 
RET 

i 

i Jet a single character from console. 

rcl ! UA C ' ractt ' " '•turned In A. 
G E T_C H A R : 



the routine starts 

! clear the parity bit 
i 1' not X-goon 
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003C 3098FD 

3 F C298 

004 1 ES99 

0043 22 



7 3 
7 4 
75 
76 
77 
78 



J N B R I . » 

CI R R I 

MOV A.SBUF 

RET ' 



END 



SYMBOL TABLE LISTING 



NAME 



ACC . . - 

A R . . • 

CONSOLES 

CR . . • 

EXIT . . 

GET CHAR 

GET LOOP 
G E T_N U M . 
00_ON. . 
I 0_R U T I NES 
LF . . • 
PUT_CHAR 
PUT_CRLF 
PUT_OATA_iT 
PUT_STR I N G 
R I . • • • 
SBUF . . • 
Tl . • • • 



TYPE 

D A D D R 
ADDR 



NUMB 

ADDR 

ADDR 

ADDR 

ADDR 

ADDR 

SEG 

NUMB 

ADDR 

ADDR 

ADDR 

ADDR 

ADDR 

ADDR 

ADDR 



REGISTER BANK(S) USED: 



VALUE 



E H 
H 



D H A 

1 5H R 

3 CH R 

002AH R 

0026H R PUB 

3 7 H R 

4 4 H 

0AM A 

00 IEH R 

OH R PUB 

0016H R PUB 

000BH R PUB 

9 8 H . A 

0099H A 

9 8 H . 1 A 



ATTRIBUTES 



SEG" I „R Q U T I NE S 
SEG - I 0_R U T I NE S 
SEG • I 0_ROUT I NE S 
SEG • I 0_ROUT I N ES 
SEG ■ I 0_ROUT I NES 
REL ■ UN I T 

SEG- I 0_ROUT I NES 
SEG" IQ_ROUTINES 
SEG"IO_RaUTINES 
S E G ■ I 0_ROUT (NES 



TARGET MACHINE(S) : 8 5 1 



ASSEMBLY COMPLETE, NO ERRORS FOUND 



Figure 5-2. SAMP2 Listing File (Cont'd.) 



MCS-51 MACRO 


ASSEMBLER 


NUM_CONVERS I ON 






system-id M C 5 - S t 


MACRO 


ASSEMBLER 


Vx.y 






OBJECT MODULE 


PLACED 


I N 


5AMP3 . OBJ 






ASSEMBLER INVOKED BY 


: ASMS! 


SAMP3.A5I DEBUG 






LOC OBJ 




LINE 


SOURCE 










t 




NAME NUM_CQNVERSION 










2 
3 


NUM., ROUTINES iioicnl CODE 










4 




R S E G N U M_R U T I N E 5 










5 




Thlj module convert! from ASCII to bl 


nary 








6 




and bock. The binary numbers are sign 


e d on 


e - b y t e 






7 




Integers, i.e. range is -128 to '127. 


Thel 


r 






8 




ASCII representation Is always 4 char 


' 3 1 


n g - 






9 




I.e. a sign followed by 3 digits. 










1 




PUBLIC ascbln, blnasc 










I 1 




USING 






3 




1 2 


ZERO EQU 1 ' 






2 B 




1 3 


PLUS EQU 






2 D 




1 4 


MINUS EQU 










1 5 
1 6 




This routine converts ASCII to binary 










1 7 




INPUT- a 4 char string pointed at by 


R 1 . 


The 






1 8 




number range must be -128 to "127, 


and 


t h e 






1 9 




string must have 3 digits preceded 


by a 


sign. 






2 




OUTPUT- a signed one-byte Integer, lo 


c a t e d 


where 






2 1 




the input string started (pointed 


at by 


R 1 ) . 






22 


ASC 8 1 N : 




ABO 1 




23 




MOV R0.AR1 ; R1 original value nee 


ded 1 


a t e r 






24 




Compute first digit value, and store 


It t n 


TEMP 


REG 




25 


TEMP EQU R3 






0002 08 




26 




INC R 






3 E S 




27 




MOV A , a R 






4 C 3 




2 8 




CLR C 






5 9 4 3 




29 




SUBB A.'iero 






0007 7SF0S4 




30 




MOV B , ' 1 






A A 4 




3 1 




M U L A B 






B F B 




3 2 




MOV TEMP , A 










3 3 




Compute the second digit value 










3 4 




INC R 
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c 


08 






D 


E 6 


35 


MOV A , »R0 


E 


9 43 


36 


5 U B B A , ' r e r o 


10 


7SF00A 


3 7 


MOV B , ' 1 


13 


A 4 


38 


MUL A B 






39 


; Add the value of the second digit to num. 


14 


2 B 


4 


ADD A, TEMP 


1 S 


F 3 


« t 


NOV TEMP. A 






4 2 


; Get third digit end Its value to total 


1 6 


08 


4 3 


[ H C R 


00 17 


E6 


4 4 


MOV A , »R0 


18 


C 3 


4 5 


CLR C 


19 


9 4 3 


46 


SUSS A.'iero 


1 B 


2 3 


4 7 


ADD A , TEMP 


00 1C 


F B 


4 8 


MOV TEMP, A 






4 9 


; Tell the sign and complement the number If the 






5 


; sign la a nlnus 


1 D 


E 7 


5 1 


MOV A , «R 1 


1 E 


B42D04 


52 


CJME A.'mlnus.pos ; Skip the next 4 lnstr's 






5 3 


; If the numher Is positive 


2 1 


E 9 


54 


MOV A, TEMP 


2 2 


F 4 


5 5 


CPL A 


2 3 


4 


56 


I HC A 


2 4 


F 3 


5 7 


MOV TEMP , A 






5 a 


; 






5 9 


; Epilogue- store the result and ill t 






6 


POS : 


2 S 


E 3 


6 1 


MOV A , TEMP 


2 6 


F 7 


62 


MOV #R 1 , A 


2 7 


22 


63 


RET 






64 








65 


; This routine converts binary to ASCII. 






66 


; INPUT-o signed 1 - by 1 e Integer, pointed at by R1 






6 7 


; OUTPUT- a 4 character string, located » h e r e the 






6 8 


; Input number was (pointed at by R1). 






69 


B I N A S C : 


E 7 


7 


SIGN bit ACC.7 






1 1 


; Get the number, find Its sign and store Its sign 
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002B 30E7U4 



2 E 
3 
3 1 



7 7 2 
1 4 
F4 



3 2 
3 3 
3 6 
3 7 
3 9 

3 A 
3 B 
3 D 
4 
4 1 
4 3 



4 4 
4 5 
4 7 
4 9 



09 

75F064 
8 4 

2 4 3 
F 7 

9 

E5F0 
7SF00A 
8 4 

2 4 3 
F 7 



09 

E 5 F 
2 4 3 
F 7 



4 A 22 



72 
7 3 
7 4 
75 
76 

7 7 
78 
79 
80 

8 I 
82 
8 3 
8 4 
8 5 
86 

8 7 
88 
89 
90 

9 1 

92 

93 

94 
95 
96 
97 
98 
99 

1 
1 I 
102 



GO 



J N B 
Next 
MOV 
DEC 
CPL 
Factor 
_0 N 2 : 
I NC 
MOV 
D I V 
ADD 
MOV 
Factor 



I NC 
MOV 
MOV 
D I V 
ADD 
MOV 
Store 
INC 

MOV 

ADD 

MOV 
note 

RET 



3lgn,go_on2 
3 Instructions 
# " I , ' m I n u s 

A 
A 

° u 1 the first digit 
R 1 

B , ' 1 
AB 

A , ' z e r o 

, ,store 
° u t the second digit 



St <"-< <> plus , lgn ( 0v5r . 
written by minus if needed) 

, Test the sign bit 
" d 1 e "egallve number, 
: Store q minus 



sign 



R I 
A , B 
B , ' 1 
AB 

A , ' z e r o 

• R 1 , A 
the third 
R 1 
A , B 

A , ' z e r o 

• R.I , A 

th «t »t return 



the first digit 



I 

END 



digit 1 ' l ° rC ' he ' eCond d '9't 



-1 thou t restoring R 1 * 
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NAME 


T 


Y P E 


V A L U 


E 


ACC . . . 


. . . D 


A D D R 


E H 


A 


A R 1 . . . 


. . . 


A D D R 


3 1 H 




ASCB [ N . 


. . ■ c 


ADDS 


H 


R 


8". . . • 


. . . D 


A D D R 


F H 


A 


B 1 N A S C . 


. . . c 


A D D R 


2 8 H 


R 


Ga_0N2 . 


. . . c 


A D D R . 


3 2 H 


R 


MINUS. . 




NUMB 


2 D H 


A 


N U M_C N V E 


R S I N 








MUM ROUT! 


N E S . C 


SEG 


4 BH 




PLUS . . 




NUMB 


2 BH 


A 


PUS. . . 


C 


A D R 


2 S H 




SIGN . . 


. . . 8 


A D D R 


E H . 7 


A 


TEMP . . 




REG 


R 3 




ZERO . . 




NUMB 


3 H 


A 


REGISTER 


B A N K ( S ) 


USED: , 


TARGET 


M A 



ATTRIBUTES 



PUB S E G - N U M_R U T I N E S 

PUB SEG-NUM_ROUTINES 
SEG-NUM ^ROUTINES 



REL -UN I T 
S E G - NUM„R OU TINES 

3 ) : 8 5 1 



ASSEMBLY COMPLETE, NO ERRORS FOUND 



Figure 5-3- SAMP3 Listing File (Cont'd.) 



system-id R L 5 I — — 

mm/dd/yy PAGE 1 

system-id M C S - 5 1 RELOCATOR AND LINKER, Vxy, INVOKED BY- 
RES! SAMPI.OBJ,SAMP2.0BJ,SAMP3 OBJ I S '- 
"TO SAMPLE t 

"PRINT (SAMPLE. LST) SYMBOLS LINES PUBLICS IXREF 

INPUT MODULES INCLUDED 
SAMPI.OBJ(SAMPLE) 
SAMP2.0BJCC0NSOLE_IO) 
SAMP3.0BJ(NUM_ CONVERSION) 

LINK MAP FOR S A M P L E ( S A rt P L E > 





TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT 


NAME 




REG 

DATA 

DATA 


H 
8 H 
1 H 


8 H 
8 H 
C H 


ABSOLUTE 
UNIT 


"REG BAh 
DATAWARE 


K " 
A 




CODE 
CODE 
CODE 
CODE 


H 
5 A H 
8 H 
F B H 


5 A H 
S 5 H 
4 3 H 
4 ■) H 


ABSOLUTE 
UNIT 
UNIT 
UNIT 


CONSTANT 
NUM _ROUT 
I O^R U T I 


-AREA 
1 N £ S 
N E S 


SYMBOL 


TABLE FOR 


SAMPLE(SAMPLE) 








VALUE 


TYPE 


NAME 























S A H 

o o i a h 

7 S H 
1 H 
8 C H 
III4H 
3 8 N 



MODULE 

SEGMENT 

SEGMENT 

SYMBOL 

SYMBOL 

SYMBOL 

SYMBOL 

SYMBOL 



SAMPLE 

CONSTANT_AREA 
DATA_AREA 
NUM 1_MSG 
N U M I 

NUM2_MSG 
N U M 2 
SCON 



Figure 5-4. RLSI Output File 






8 H 


SYMBOL 


STACK 


c 


B H 


SYMBOL 


START 


c 


A 4 H 


SYMBOL 


S U M_M 5 G 


D 


1 8 H 


SYMBOL 


SUM 


D 


8 D H 


SYMBOL 


TH 1 


D 


8 9 H 


SYMBOL 


T M Q D 


3 


8 8 H . G 


SYMBOL 


T R 1 


C 


5 A H 


SYMBOL 


T Y P 0_M S G 






E N D M D 


SAMPLE 






MODULE 


CONSOLE_I 


D 


E H 


SYMBOL 


A C C 


D 


H 


SYMBOL 


A R 


N 


D H 


SYMBOL 


C R 


C 


1 1 H 


SYMBOL 


EXIT 


C 


1 3 7 H 


SYMBOL 


G E T_CHAR 


C 


1 2 S H 


SYMBOL 


GET_LOOP 


c 


1 2 1 H 


PUBLIC 


GET_NUM 


c 


1 3 2 H 


SYMBOL 


GO_ON 


c 


F H H 


SEGMENT 


I Q_R U T 1 N E S 


N 


9 0AH 


SYMBOL 


LF 


c 


1 1 9H 


SYMBOL 


PUT_CHAR 



system-id R L 5 1 



mm/dd/yy PAGE 



F 9H 
1 I I H 
1 GH 
9 8 H 
9 9 H 
0098H . 



PUBLIC 
PUBLIC 
PUBLIC 
SYMBOL 
SYMBOL 
SYMBOL 
ENDMOO 



PUT 
PUT 
PUT 
R I 

SBUF 
T I 

CONSOLE 



C R L F 

DATA_STR 
STRING • 



E H 
' H 
0-0 8 H 
F H 
8 H 



MODULE 
SYMBOL 
SYMBOL 
PUBLIC 
SYMBOL 
PUBLIC 



N U M_C N V E R S I O N 

ACC 

AR 1 

ASC8 I N 
B 

Bl NASC 
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c 


E 2 H 


SYMBOL 


GO_0N2 


N 


2 D H 


SYMBOL 


MINUS 


C 


OBOH 


SEGMENT 


NUM_ROUT I NES 


N 


2 BH 


SYMBOL 


PLUS 


C 


D S H 


SYMBOL 


P S 


B 


£ H . 7 


SYMBOL 


SIGN 


H 


3 H 


SYMBOL 


ZERO 






ENDMOD 


NUM_CONVERS 1 ON 



INTER -MODULE 


CROSS - 


REFERENCE LISTING 




USAGE 


MOOULE NAMES 


ASCB 1 N . . . . 


CODE ; 


NUM_CQNVERS I ON SAMPLE 


B I N A S C . . . . 


CODE; 


N U M_ CONVERSION SAMPLE 


G E T_N UM . . . 


CODE ; 


CONSOLE_IO 


SAMPLE 


P U T_C R L F . . . 


CODE; 


CONSOLE_I O 


SAMPLE 


PUT_DATA_STR . 


CODE ; 


CONSOLE_I O 


SAMPLE 


PUT^STR I N G . . 


CODE; 


CONSOLE^IO 


SAMPLE 



, Fl 9ur» 5-4. RL51 Output Fit* (Cont'd.) 
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Using the Locating Controls 

The second example shows now to use the PRECEDE control to specify an order for 
data segments, in this case because the RL5I algorithm lor locating segments results 
in a segment being left out. 

The program is named TEST01. After assembly, the listing of TESTOI.OBJ is as 
shown in figure 5-5. The program's code sequence is irrelevant to the example. The 
two DATA segments. SEG! and SEG2. and the BIT segment, BIT3, are the points 
of interest for this example. 

SEG I is 21 H bytes long; SEG2. 50H bytes long; SEG 3. one bit long. The assembler 
listing also shows working register hank (S bytes long, absolutely located at addresses 
00H through 07H). 

All these segments are to be located in the on-chip data RAM of an 8051. For the 
8051, the dircctly-addressabie on-chip data RAM is SOU bytes long (addresses 00H 
through 7FH): addresses 20H through 2FH are bit-addressable. The working regis- 
ters may occupy the first 2011 bytes of the space. To see what RL5I does with this 
program, enter the command 

R L 5 1 TEST01.08J 

The RL51 listing Tile is shown in figure 5-6. ERROR 107 informs us that the locate 
attempt for SEGI would overflow the data space; SEGI was ignored (not located) 
for this reason. The link map shows the following assignments for the remaining 
segments; 



Addresses .Segment 

00H - 07H Register Bank 

08H - 1FH GAP 

20H SEG3 (one bit at bit location 0) 

20H.I-20H.7 GAP 

2111 -71H SEG2 (50H bvtes) 



After these segments have been located, there is not enough room for SEGI (21H 
bytes). However, there would be enough room if SFGI were located before the BIT 
segment. To obtain this result, the command is 

RL51 TEST01.0BJ PRECEDECSEG1 ) 



The RL51 listing file for this example is shown in figure 5-7. The PRECEDE control 
caused the link mapping to be as follows: 



Addresses Segment 

0OH - 07H Register Bank 

08H - 28H SEGI (21 H bytes) 

29H SEG3 (one bit at bit location 0) 

29H.I-29H.7 GAP 

2AH-7AH SEG2 (50H bytes) 

Refer to Chapter 2 for details on RL51's allocating algorithm. 



Using RL51 with PL/M-51 Modules 

The third example shows how to use RL51 with object modules produced by 
PL/M-5I. The example shows the use of PLM5I LIB and demonstrates PL/M-5I 
generated segments and the PL/M-51 to ASM5I linkage. 
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The entire application introduces a way to hall ICE-5I the 805 1 In-Circuit Emulator 
Program at run time. The procedure CHECK.EQUAL in the PL/M-51 module 
CHK.fcQ checks if an arithmetic expression is true, [f vcs. it calls the HALTJCE 
assembler routine, which causes ICE5I to stop the program that is currently running 
devVc^ment proc° Sranl ' $ ''"^"""^ " arn P le mcn:l >' int<:nds 'o show the program 

The PLM5I main module CHK_EQ is compiled by 
PLMS1 CHKEQ.P5I DEBUG PM(90) 
The output of the compilation is shown in figure 5-8. 
The ASM 5 1 module HLTICE is assembled by 
« 1 HLTICE. AS 1 DEBUG P W ( 9 > 
The output of the compilation is shown in figure 5-9. 
RL5I is invoked by the following command; 

Hf1 CHKEQ. OBJ, HLTICE. OBJ, PLMS1. LIB I I 8 C f P H ( 7 J ) 

Dt^.'c'.'lVn'^,'*' P re - tran,,ated in P u t modules, along with the mandatory library 
PLM5 .LIB. PLM5I.L1B must be linked whenever a PL/M-51 module participates 
in the linkage. The listing files arc shown in figures 5-8 and 5-9. The result of the 
linkage is shown in figure 5-10. 

The result of a linkage process that includes PL/M-51 modules deserves an expla- 
nation. The following paragraphs describe the modules, segments, and symbols that 
appear in the output listing of such a linkage. The explanation refers to the actual 
example (figure 5-10). 

In addition to the two input modules CHK.EQ and HALTJCE. RL5| pulled some 
modules (from PLM51.LIB. The two modules -P0034 and 7P0038 contain common 
r-Sv 'ii, run "" mc rc,ullnes and were P ullcd 'O resolve calls to those routines in the 
L i T1,C module: ?PIV0R contains the initialization routine (set the 

stack pointer, set PSW), and is pulled whenever a linkage process encounters a main 
module written in PL/M-51. 

ImSS^J^SSLSS^-^ prog are ,he user segmtnls as defmcd « ,hc 

HALI. ICE module. The code segments 7P0034S. 7P0C8S and ''PIVORS 
are the code segments of the previously explained run-time routines. 

All segments whose names are of the form 7CHK_EQ7any are segments generated 
by PL/M-51 as result of compiling module CHK.EQ. The prefix ''CHK.EQ'' 
indicates that the segment belongs to the CHK.EQ module. The suffix indicates the 
segment tyre; e.g. PR stands Tor the PRogram CODE segment. CO for the COnstant 
CODE segment. DT for DATA segment, and B[ for BIT segment. 

On-chip segment names may be followed by a register bank number (0-1) This 
number indicates the register bank that must be in effect while data in this segment 
is accessed. r 

The JSTACK segment was discussed before. Note that this segment is not supplied 
by the user, but is pulled automatically from PLM5I.LIB because the main module 
is written in PL/M-51. The absolute segment at 0OO0H-OO02H contains the reset 

C ° n " S ' S 0f 3 JUMP 10 the initialisation routine contained in the 
PIvORS segment. 
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Mml or pl/M-M -generated relocatable segments ^^^'eq^M^iSS is 
^auenf exeepiion is the program code ^M). which is the 

default used by .the compler. Ann h« lk» ^ J Hfe! irt declared wrthO. the 
DRESSABLE DATA segment generated wnen 
PL/M-51 source program- 

L , u ihr IJtREf report. Symbols whose 

User symbols appear in the previously represent entry points 

?T eq :ri'a" S/^tw «~ PLM5I LIB ,e,.. .be symbol 
^^/irrc^r^d^srn^e^odule 7PO034). 

j.^iBYTF or ''procedure^BlT (e.g.. 
Svmbols in the ^J^TbiT^I^ used for passing parameter, , to 
ill At T ICCBYTE; are DATA and BI a " orc , BYTE and WORD 

apjroprtate external procedures (« ^,mp to « ^ , 

parameters are placed at DATA ' glT address start. ng at 

iHALT ICE7B1T (see also the /•/./« « u - 
ASM50- 
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L -J U 1J 



E 



UJ E 



WP1*lTU)fx(II(T10-(Mm"ri71tC^ 



rjio-iMnvi/iOJr-rrifji 
^cvjrsjtvc\iojc\jr>jf\jfviCNj 



O i- 
H U > Ul 



t) m uj 

£ " E "* 

t uj uj m 
a -> a 

^ m to • 

w o « • 



i/i o tn — 
<M 

«• n m to 

u. er> #m ut 



in ■ 



i e» an <_> ui 



(duo 



system-id R L S 1 

^ -c*-s, «u«m - L.ll .1 — ED BY: 

RL51 TEST 1 . OB J 

, NPU T MODULES INCLUDED 
TESTOl.OBJ(TESTOI) 



FOR TESTO UTESTO 1 ) 






TYPE 


BASE 


LENGTH 


RELOCATION 


REG 
BIT 
DATA 


H 
8 H 
2 H 
2 H . I 
2 1 H 


9 H 
1 8 H 
H . 1 
H . 7 
5 H 


UNIT 
UNIT 


CODE 


H 


1 2H 


UNIT 



SEGMENT NAME 



"REG BANK " 
• • • GAP ' ' * 

SEG3 

... GAP * 1 1 

SEG2 

PROG 



IGNORED SEGMENTS 
SEG 1 

ERROR 107: ADDRESS SPACE OVERFLOW 
SPACE : DATA 
SEGMENT : SEGI 



Figure 5-6. RL5 . Listing File without PRECEDE 



system-id R L 5 1 

system-id MCS-SI RELOCATOS AND LINKER. Vxy, INVOKED BY: 
RLS1 TEST01.0BJ P R E C E D E ( S E G 1 ) 

INPUT MODULES INCLUDED 
TESTO 1 . OBJ(TEST0 I > 

L I NK MAP FOR TESTO 1 ( TESTO I ) 

TYPE BASE LENGTH RELOCATION SEGMENT NAME 



REG 
DATA 
B I T 

DATA 

CODE 



H 

8 H 

2 9 H 

2 9 H . 

2 A H 

H 



8 H 

2 I H 

H . 

H . 

5 H 

I 2 H 



UNIT 
UNIT 



UNIT 



UNIT 



"REG BANK 0' 

SEGI 

SEG3 

... GAP ... 

S E G 2 

PROG 



Figure 5-7. RL51 Listing File with PRECEDE 



PL/M-51 COMPILER 

system-id PL/M-51 V 
COMPILES INVOKED BY : 



I CE5 1 



Chcc t /Ha I t 



mm/dd/yy PAGE 



SYS< em -' dP }'. n .:Ml* y a ,. .,.51 chkeq.pSI debug p. (90) 



1 1 

2 1 

3 2 
5 1 
S 2 

7 2 
9 1 

10 1 

I 1 I 
1 2 1 



/• Check _equal: 
/ • Check If 
/• expected 


com 
r e i 


pirlioi yields the 

ult. If not, call ' 

utlne lo return to ICE. 


c h k _e q : 
DO i 







^PR^CEDURE ( all, ..1*. eq^-ltch, U M fj * M I f 
DECLARE (vaM, "ORD. -W"" th 



END: 



check _equal : 

PROCEDURE ( 
DECLARE 
( v a 11 , 
e q * 1 1 

IF ( ( v a 1 I 
THEN 
END checks 

/• dummy main 

DECLARE 

pi WORD 
I ) WORD 



all , val2, eq_ 5 -ttch> PUBLIC; 

va 1 2 ) WORD, 
t ch BIT; 

<> val2) <> eq_!wltch) 
ALL hal t_lc= (vail, va 12 , =q_'» 
q u a 1 ; 

proqram * / 
CONSTANT (3), 



Itch) 



CALL check __equal(pl*3l> 27 / J t 
END c h k _ e q ; 



1 ) 



Flgurn 5-8. PL/M-51 Listing File of CHK_EO 



MODULE INFORMATION: 
CODE SIZE 
CONSTANT SIZE 
DIRECT VARIABLE SIZE 
INDIRECT VARIABLE SIZE 
BIT SIZE 

BIT-ADDRESSABLE SIZE 
AUXILIARY VARIABLE SIZE 
MAXIMUM STACK SIZE 
REGISTER-BANK(S) USED: 
3 4 LINES READ 
PROGRAM ERROR(S) 
END Of PL/M-51 COMPILATION 



(STATIC-OVERLAYABLE) 



5 7 H 

2 H 

2 H • 4 H 
H • H 
H • 1 H 
H • H 

H 

G H 





8 7 D 
2 D 
2 D • 
D • 

o o • 

D • 
D 
S D 




1 





Flgura 5-3. PL/M-51 Listing Flla of CHK_EQ (Cont'd.) 



NC S-5« MACRO ASSEMBLER 



,ij CS l - Halt •** 



mm/dd/yy \ * & E 1 



i »rs-S1 MACRO ASSEMBLER ViM 



1 

to 

O 



LOC OBJ 






2 



AC 
2 A D 
4 A E 



LINE 



1 
2 
3 
4 

S 

6 

7 

8 

9 
t 
1 1 
1 2 
1 3 

I 4 

1 S 

1 6 

1 7 

1 8 
t 9 

2 
2 1 
2 2 
2 3 
2 4 
2S 
26 

2 7 
28 
29 
30 

3 1 



SOURCE 
» t L t 1 e I ' ' 



iecsi - » alt '•' ) 



H.lt_lct: i „ R 4 S , R67, 

to rtUrn to ICE. 



NAME fc»U-»e« 

PUBLIC Ml'- 1 "' 

M 'J1 SEGMENT BIT 

byte. SEGMENT DATA 

prog SEGMENT CODE 

RSEG t> 1 1 ' 

'ha 1 t_i c e ' b t t : 

b i t _p a r : 

D B I T 1 

RSEG ny'" 

f ( r 3 t _p a r : 

DS 2 

second _par : 

DS 2 



>h.l t_leifbl t . 



> ha 1 t_l ce 'by t e 



halt 



MOV 



RSEG prog 
ice: 

MOV R 4 . f 1 ' » t-P» r 

MQV RS , ( 1 r ' t_par • 1 

(6 , <t c " d -P ar 



m ove (It par to P 1 « <= < 
2"0 par to pi." 



Figure 5-9. ASM51 Listing File of HLTICE 



0006AF0O F 32 MOV 

8 A 2 F 33 MOV 

000AAS 3 5 DB 

0OOB0O 36 NOP 

C 3 7 NOP 

000O00 38 NOP 

E 2 2 3 9 RET 

4 

4 1 END 



17 , ncond_par • I 

C , b I t _p a r ; nave bit par to place 

A 5 H ; Illegal op-code. 

; Mill stop ICE-SI If you 

; type "GO TIL 0PC IS AS" 

; you can continue after 

; stop. 



MCS-S1 MACRO ASSEMBLER *-- ICESI - Halt -■' 

SYMBOL TABLE LISTING 



NAME 


T 


Y P E 


V A L 


u 


E 


A T 


T R I 


'HALT_ICE'BIT. 


B 


ADDR 


H . 





R PUB 


SEG 


•BITS 


' H A L T_ 1 CE'BYTE 


D 


ADDR 


H 




R PUB 


SEG 


-BYTES 


BIT_PAR. . . . 


8 


ADDR 


H . 





R 


SEG 


•BITS 




B 


SEG 


1 H 






REL 


•UNIT 




D 


SEG 


4 H 






R E L 


•UNIT 


FIRS T_P A R . . . 


D 


ADDR 


H 




R 


S E G 


•BYTES 


HALT ICE . . . 


C 


ADDR 


H 




R PUB 


S E G 


•PROG 


PROG 


C 


SEG 


F H 






R E L 


•UNIT 


SEC0ND_PAR . . 


D 


ADDR 


2 H 




R 


SEG 


•BYTES 


REGISTER BANK(S) 


USED : , 


TARGET 




MACHINE(S) : 


8 5 1 



B U T E S 



ASSEMBLY COMPLETE, NO ERRORS FOUND 



Figure 5-9. ASMS 1 Listing File of HLTICE (Cont'd.) 



system-id R L 5 1 



mm/dd/yy PAGE 1 



ISIS-II MCS-S1 RELOCATOR AND LINKER, Vx.y, INVOKED BY: 
RL51 CHKEQ . OBJ , HLT I CE . OBJ , PLM5 I . L I B IXREF PW(72> 



INPUT MODULES INCLUDED 
CHKEQ . 08J(CHK_EQ> 
HLT I CE . B J ( HA LT_I CE ) 
PLM51 .LIBC7P0034) 
PLMS 1 .LIBCP0038) 
PLMS1.LIBC?PIV0R> 



LINK MAP FOR CHKEQ ( CHK_E Q ) 
TYPE BASE 



REG 
DATA 
DATA 
DATA 

B I T 
B I T 

I DATA 

CODE 
CODE 
CODE 
CODE 
CODE 
CODE 
CODE 



H 

8 H 

C H 

1 H 

! 2 H 

2 H 

2 H . 

2 H . 

2 I H 

H 

3 H 

SAH 

7 H 

7 F H 

8 B H 

9 4 H 



LENGTH 



8 H 

4 H 

4 H 

2 H 

EH 

H . 

H , 

H . 

1 H 

3 H 

5 7 H 

1 6H 

F H 

C H 

9 H 

2 H 



RELOCATION 



UNIT 
UNIT 
UNIT 

UNIT 
UNIT 

UNIT 

ABSOLUTE 

I N8LOCK 

UNIT 

UNIT 

UNIT 

UNIT 

UNIT 



SEGMENT NAME 



" 



"REG BANK 
BYTES 

'CHK_EQ'DT'0 

1 C H K_E Q ? D T 
... GAP • * • 

? C HK^E Q ? B I ? 
BITS 

... GAP ... 

'STACK 



'CHK_EQ'PR 

'P0038S 

PROG 

? P 3 4 S 

' P I V R S 

' C H K_E Q ' C 



Figure 5-10. RL5 1 Listing File of CHK EQ 




SYMBOL TABLE FOR CHKEQCCH K_E Q ) 



VALUE 


TYPE 


NAME 




MODULE 


C H K_E a 


C : 3 H 


PUBLIC 


CHECK__EOUAL 


C : 3 3 H 


SYMBOL 


C H K__E a 




P R C 


CHECK __ EQUAL 


D : C H 


SYMBOL 


V A L 1 


D : E H 


SYMBOL 


V A L 2 


B : 2 H 


SYMBOL 


EQ_SW ITCH 


C : 9 4 H 


E N D P R C 


C H E C K_E Q U A L 


SYMBOL 


P I 


D : 1 H 


SYMBOL 


S I 
1 


C : 3 3 H 


LINE' 


C : 3 H 


LINE' 


5 


C : 3 H 


LINE' 


7 


C : 1 F H 


LINE' 


8 


C : 0032H 


LINE' 


9 



system-id R L 5 I 

C : 3 3 H LINE' 
C:O0SAH LINE' 



mm/dd/yy PAGE 2 



1 1 

I 2 - 

ENDMOD CH K_E Q 



: 2 H . 
8 H 
2 H . 

o a 2 a h . 

8 H 
8 H 
7 H 
7 H 
A H 



MODULE 

PUBLIC 

PUBLIC 

SYMBOL 

SEGMENT 

SEGMENT 

SYMBOL 

PUBLIC 

SEGMENT 

SYMBOL 

ENDMOD 



H A L T_I C E 

' H A L T_ I C E ' B I T 

'HAL T_I CE ' B Y TE 

B I T_PAR 

BITS 

BYTES 

F I R S T_P A R 

HAL T_l CE 

PROG 

SECOND_PAR 
HALT I CE 



Figure 5-10. BL51 U.llng File ol CHK EQ (Cont'd.) 
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Introduction 

LIB5I allows you to create, modify, and examine library Tiles. It may be executed in 
interactive or noninteractive mode. In both cases, L1B51 can be invoked directly or 
by a submit file. 



Invoking LIB51 
Noninteractive Mode 

Following is the general syntax for invoking in non-interactive mode: 
I directory I device I L I B 5 1 command 

The librarian will then respond with the sign-on message. It then executes the given 
command and returns immediately to the host operating system. 



Interactive Mode 

Following is the general syntax for invoking LIB5I in interactive mode: 

I directory I device 1 L I B 5 1 

LIB5I will then respond with its sign-on message. It will then present the prompt (•), 
requesting that you enter LIB51 commands. After each command is executed, another 
prompt will appear as the librarian awaits entry of the next command. This process 
continues until the EXIT command is entered, thus terminating LI 85 1 . 



Character Set 

The LIB51 character set consists of the letters A-Z, the digits 0-9 and the special 

characters ?, @, and _. 

LIB51 Commands 

Table 6- 1 summarizes the LIB51 commands. 



Command Entry 

It is often necessary to extend the LIB command to more than one line. Use an 
ampersand (&) to indicate that you have not entered the complete command and are 
extending it to another line. The ampersand continuation character may be placed 
anywhere that a space would normally appear in the command line. That is, the 
continuation character may be placed before or after commas or parentheses and 
before or after control words. Any characters that appear on a line to the right of the 
ampersand und to the left of the carriage return terminating the line are ignored. 
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Table 6-1. LIB51 Commands 



Command 


Abbreviation 


Oascrlpllon 


ADD <tile|(module|,...))l> [....] TO library Jile 


A 


Adds modules lo a 
library 


CREATE library file 


C 


Creates a library 
file 


DELETE library Jile(module|...|) 


D 


Deletes modules 
from a library 


EXIT 


E 


Terminates 
session with LIB51 


EXTRACT { fiie[(module|....j)j i [....) TO OH 


X 


Extracts modules 

from libraries 


HELP 


H 


Displays syntax ol 
LIB51 commands 


LIST <liie|(module|...|)|) (....} (TO (8»| | PU BL ICS | 


L[P| 


Lists modules 
contained in librar- 
ies, and optionally 
lists an publics 


REPLACE < lrte|(moduie|. ) |, ...\ IN library JM 


R 


Replaces modules 

in a library 



Whenever you enter the continuation character. LIB51 responds by beginning a new 
line with the continuation prompt— iwo asterisks (**). LIB51 then waits for you lo 
enter the additional line of inpul. IT you cannot complete the command on the second 
line, use more ampersands lo continue Ihe process umil Ihe command is completely 
entered. 

A semicolon may be placed on any command lo slarl a commenl. L.IB5I will ignore 
all characters that appear to Ihe right of the semicolon and to the left of ihe carriage 
return lhal terminates the line. If you enler an ampersand lo Ihe right of a semicolon, 
the ampersand will be trealed as part of a comment and nol as Ihe continuation 
character. 
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Co...mand Descriptions 

Following are the descriptions of the LIB5I commands. 

ADD 



Syntax 

ADD :♦»>•"**-«••.:. 1 1 1 > ...... to i^j* 

Abbreviation 

A 



Description 

2*f£iS? a " 0WS '° ^ ^ ^ '° *• «b«r, file specified 
be added to Ihe designated ^ tbrarv Th, L 1 " C ° n,ained Within lhal file *® 

^.T^u'do^t'sSy?^ 32 M22 wi ,', h f wi,hom a ,isl 

Ihe input library wH hTa Jed " ,fo SSStoTS' Ir^ m °* Ui " C0 " ,ai " ed 
The destmalion .ibrary mus, already „isl before ,he ADD command is entered. 



Examples 



".OP 5IH,C05,TAW TO USER.LIR 



This command adds the three files SIN ,„,jtam. ,l . 

USER. LIB. ' and TAN 10 lhe destination library 



lo continue the command. C lhe usc of the ampersand 



CREATE 



Syntax 

CREATE library die 

Abbreviation 

c 



Description 

The CREATE command causes an empty library file that has been named in the 
command to be created. If the file already exists, an error message » issued and the 
command terminates. 



Examples 
I. 

This command creates the empty library file SLEAZO.LIB. 



CREATE S L E A Z V 1 I I 
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DELETE 

Syntax 

DELETE library file ( module name [,...]) 

Abbreviation 

D 

Description 

The DELETE command removes the specified modules from the designated library 
file. Modules can be deleted from only one library at a time. If any of the elements 
specified for deletion cannot be located, a warning is issued. 



Examples 



DELETE SLEAZO.LIBCTRUTH, VALUE) 



This command deletes the modules TRUTH and VALUE from the library 

SLEAZO.LIB. 
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EXIT 



Syntax 
EXIT 



Abbreviation 



E 



Description 
command is ignored. 



Examples 



EX TRACT 



Syntax 

EXTRACT ( tile t ( module t ,...]) 1 ) t ..... 1 TO tile 

Abbreviation 
x 

Description 

The EXTRACT command builds an ordinary object Tile from the specified files and 
library members. The extracted Tiles are not deleted; they remain unchanged (i.e., 
they are nondestructively copied to their destination). 



Examples 



1. 



I BtWORTH ,FREE> TO PROLES 



The modules WORTH and FREE are nondestructively extracted from 
SLEAZO LIB and placed in PROLES.OBJ. 
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HELP 



Syntax 
HELP 



Abbreviation 

H 



Description ^ ^ 

The HELP command mm^ja^MM^^^^^£ 
appear on the Bering commands. The following inlormal.on mil 

LIB51 if you require help wnen eniwijua 
appear on the screen: 

ADD (Wei ImoCufet , . . . HI > t . 

CREATE '* raf y We . , , 

DELETE library Jile ( module t 

EXTRACT (modu/e( , . . . 1 > 1 > I 

L15T (Wei (™dute I 1 • 

REPLACE '(Wei (.modulel , . • • i 



, , , ] TO library Jile 
. . 1 TO We 

_ j | T0 me) [PUBLICS! 
',*,,] in library Jile 
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LIST 



Syntax 

LIST < tile I ( module I ,,..]) 1 > 1 , ... 1 I TO file 1 (PUBLICS) 



Abbreviation 



L (PI 



Description 

The LIST command prints the names of the modules, and. optionally, the names of 
the public symbols (if you specify PUBLICS) lo the specified destination output file. 
If you do not enter the TO clause, the listing will be directed lo the console output. 
PUBLICS specifies that in addition to Ihe module names, all public symbols contained 
in those modules will be listed. 



Examples 

• IIHaTlflBTIBMB—l Ml 

The names of all modules in the library USER. LIB are listed. 

• WMMMjlllUJm.l JMJIM»»^1i^—i 



All public symbols in the module TEMP in the library USER. LIB are listed. 
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REPLACE 



Svntax 

REPLACE (Wei (module! 



Abbreviation 
I 

Description , 
Tnc REPLACE -£5^^ 



Examples 



1. 



■ n of WORTH is added to the library SLEAZO.LIB; the new 
The newer version or WUKi n 
file FREE is also added. 



Summary of RL51 Controls 



A 



Table of Basic Definitions 

Table A- 1 gives definitions of basic terms used in the command format summary. 



Table A-I . Definitions of Common Terms 



Term 


Definition 


name 


Names can be from 1 to 40 characters long and must be composed 
of letters A - 2. digits - 9. or soecial characters {i. @. J. The 
first character must be a letter or a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid filename reference or device reference. See next two items 
lor examples. 


filename 


A reference to a disk tile. 


device 


A reference to a non-disk device. 
Examples: :LP:. :CO:. :TO: 


value 


A 16-bit unsigned integer 

Examples: 10118. 304Q. 4096D (or |usl 4096). 0C300H 


address 


Same as value. 



RL51 Command Format Summary 

Here is a summary of the syntax of the RL5I invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL51 command has the overall format 

( directory I deuce IRIS 1 input-list I T output-file ) I control-list ) 
where 

directory \ device ; the directory or device where RL51 resides. 

input-list : • input-file I module-list 1 I , ... I 

input-file : • filename ; see table A- 1 

module-list : • ( module-name I , . . . 1 ) 

module-name : • ; see table A-I 

output-file :■ filename; sec table A-I 

control-list : ' control . . . 
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listing-control 
linking-control 
control ! ■ < locating-control > 
I configuration-control 
I overlay-control j 
( P n nt \ 
I pagewidth j 



listing-control 



print 



pathname 
pagewidth : • 
value : ■ 



I map 
■ / symbols > 
| publics 
I dries 

V ixrel t 
PRINT [ {pathname) ) 1 
H OP R I NT I 
j sec lable A- 1 
PAGEWIDTH ( value > 
sec lable A-l 



map ! ' 

symbo/s 
publics 



lines 



MAP | 
N M A P | 

I SYMBOLS 
" | NOSYMBOLS 

(PUBLICS I 
\ HOPUBL I CS | 

LINES 1 
I N L I N E S 



ixref 



I X R E f I selection-list 1 1 
HOI «REf I 
seiection-hst I ■ I selection-item 



1 ) 



selection-item 



generated 



libraries 



[ generated \ 
| libraries | 

j GENERATED 1 
\ NOGENE R A T E D 

LIBRARIES I 
NOLlBRARIES j 



linking-control I ■ 1 

debugs ymbo/s 
debuglmes ■■ • 
debugpublics 

locatmg-controls : 



NAME t fliOdWN»W»'| 
debugsymbols \ 
debuglmes 

debugpublics * 

(DEBUGSYMBOLS J 
" (NODEBUGSYMBOLS| 

I DEBUGL 1NES I 

|nodebuglines| 

DEBUGPUBL ICS i 
^ODEBUGPUBLICSl 

PRECEDEx 



( segment I 




, 1 ) 



segment : ■ segment-name U address)) 



Summary o( RL51 Control*"' A-3 



segment-name 
address : • ; 



: • ; see lable A-l 
see table A-l 



contiguration-control : • ramsize 

ramsize : ■ RAMSIZE t value ) 
see lable A-l 
OVERLAY 



value : 
overlay-control 
overlay-unit 

ov-moduie-name 



NOOVERLAY "OWfUTWM... 
ov-module-name calls ov-modute-name 



1 ) 1 



calls 



module-name 
• > or ) 



module-name J 
■ ; see table A-l 



Tables of Listing, Linking, Locating, and 
OveriayingControls 

Tables A-2 through A-6 describe the RL5I controls. Table A-7 gives abbreviations 

for the controls. 



Notes On Locating Controls 

The following imles refer Ui table A-4. 

I Hit addresses Tor nun-BIT segments in the HIT control must be on hyle bounda- 
ries; that is. they must be divisible by eight. (BIT-type segments can he aligned 

on bit boundaries. I 

2. The range of addresses for the I DATA control is dependent on the target machine. 
The 8051 has 128 bytes (addresses 00H 7HI). See the RAMSIZE control in 

[his context. 

y. The STACK control specifies which segments are to be allocated uppermost in 
the IDATA space. The memory accessed starts after the highest on-chip RAM 
address occupied by any previously allocated segment, and continues to the top 
of the IDATA space. 

NOTE 

This control has no other effect on any segments. 

The IDATA '.'STACK segment, if it exists, is placed higher than segments 
thai were mentioned in the STACK control. 



Table A-2. Listing Controls and Switches 



Control 


Eft«ct 


PRINT \{pathn»me)\ 
NOPRINT 

PAGEWIDTH (value) 

MAP 

NOMAP 

SYMBOLS 

NOSYMBOLS 


SendsVhe listing hie to the tile or device specified by 
pathname 

Suppresses the listing tile; overrides any ol the loltowing 
listing controls. 

Specifies the maximum page width to be used. 
Outputs memory map to link summary. 
Suppresses memory map. 
Outputs local symbols to symbol table. 
Suppresses local symbols. 
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Table A-2. Listing Controls and Switches (Colli . | 



Control 


Ett.ct 


PUBLICS 

NOPUBLICS 

LINES 

NOLINES 

IXREF |(se/ecfton-i7sf )| 
NOIXREF 


Outputs public symbols to symbol table. 
Suppresses public symbols. 

Outputs line numbers lo symbol table (high-level language 
translators only). 

Suppresses line numbers. 

Appends intermodule cross-relerence report to print file. 
Suppresses the intermodule cross-reference report 



NOTE: The default lor any conlrol (except IXREF) is the positive form (PRINT, MAP. SYMBOLS. 
PUBLICS, and LINES). 



Table A-3. Linking Controls and Switches 



Control 


Etfecl 


NAME (module-name) 


Specifies the name of the output module it the NAME control is 
omitted, the output module name defaults lo the name ol the first 
input module processed. 


OEBUGSYMBOLS 


Copies local symbol information to output tile 


NODE BUGS YMBOLS 


Suppresses local symbols 


DEBUGPUBUCS 


Copies public symbol information to output tile 


NOOEBUGPUBLICS 


Suppresses public symbols 


DEBUGLINES 


Copies line number information |highlevel language translators 
only) to output tile 


NODEBUGLINES 


Suppresses line numbers. 



NOTE: For ai< linking controls except NAME the default is the positive form (DEBUGS YMBOLS. 
DEBUGPUBUCS. and DEBUGLINES). 

Table A-4. Locating Controls 



Control 


Address Space 



Address Range 
(Hex| 


Segment Types 
land Attributes) 


PRECEDE 


Register banks and bit- 
addressable space in 
on-chip data RAM 


00H.2FH 


DATA (UNlT-aligned); 
IDATA 


BIT 


Bit-addressable space 
in on-chip data RAM 


00H . 7FH 
(see note 1) 


BIT: DATA: IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


00H - 7FH 


DATA (UNIT-aligned). 
IDATA 


IDATA 


indirectly-addressable 
on-chip data RAM 


00H • OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 
note 3) 


Same as IDATA 


Same as idata 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 



Table A-5. Configuration Control 



Control 


Effect 


RAMSIZE (value) 


Specifies the amount ol on-chip RAM the ohiect is aimed to 



Summary of RL 51 Controls A-5 



Control 



OVERLAY {OV„rlsy. u „„ s) 
NOOVERLAY 



L 



Table A-6. Overlay Controls 



Etfecl 



Suppresses the overlaying ol dala segments 



Table A-7. Abbreviations for Command Words 



Command Word 



BIT 

CODE 

DATA 

DEBUGLINES 

DEBUGPUBUCS 

OEBUGSYMBOLS 

GENERATED 

IDATA 

IXREF 

LIBRARIES 

LINES 

MAP 

NAME 

NODEBUGLINES 

NODEBUGPU8UCS 

NODEBUGSYMBOLS 

NOGENERATED 

NOIXREF 

NOLIBRARIES 

NOLINES 

NOMAP 

NOOVERLAY 

NOPRINT 

NOPUBLICS 

NOSYMBOLS 

OVERLAY 

PAGEWIDTH 

PRECEDE 

PRINT 

PUBLICS 

RAMSIZE 

STACK 

SYMBOLS 

TO 

XDATA 



Abbreviation 



SI 

CO 

DT 

DL 

DP 

OS 

GN 

ID 

IX 

LB 

LI 

MA 

NA 

NODL 

NODP 

NODS 

NOGN 

NOIX 

NOLB 

NOLI 

NOMA 

NOOL' 

NOPR 

NOPL 

NOSB 

OL 

PW 

PC 

PR 

PL 

RS 

ST 

SB 

TO 

XD 



RL51 Error Messages 



RL5I error messages describe warnings, errors, and fatal errors. A warning is a 
detecled condition that may or may not be what the user desired: a warning does not 
terminate the link/locate operation. An error does not terminate operation, hut 
probably results in an output module thai cannot be used. A fatal error terminates 
operation of RL5I. 

This appendix lists the warning, error, and fatal error messages in that order. The 
text of each message is in UPPER CASE. A brief explanation of the probable cause 
for the error condition accompanies each error message. 



Warnings 

WARNING t ! UNRESOLVED EXTERNAL SYMBOL 
SYMBOL: external-name 
MODULE: file-name(module-name) 

The specified external symbol, requested in the specified module, has no matching 
public symbol in any of the input modules. 

WARNING 2: REFERENCE MADE TO UNRESOLVED EXTERNAL 
SYMBOL: external-name 
MODULE: file-name(module-name) 
REFERENCE: code-address 

The specified unresolved external is referenced in the specified module at the specified 
code address. 

WARNING 3 : ASSIGNED ADDRESS NOT COMPATIBLE WITH 

ALIGNMENT 
SEGMENT: segment-name 

The address specified for the segment in a locating control is not compatible with the 
segment's alignment. The segment is placed at the specified address, violating its 

alignment. 

WARNING 4 ! DATA SPACE MEMORY OVERLAP 
FROM: byte. bit address 

TO: byte. bit address 

The data space in the given range is occupied by two or more segments. 

WARNING Si CODE SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The code space in a given range is occupied by two or more segments. 

WARNING Bi XDATA SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The xdala space in the given range is occupied b> two or more segments. 
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EARNING 7, MODULE HA«E HOT UNIQUE 
MODULE: nie-name(module-name) 

The specified name was used » -he m** name for more than one module. The 
specified module is nol processed. 

WARNING ., MODULE ^HH.CIU RtflHESTEP FROM 

ANOTHER F ILE 
MODULE' lile-name(module-name) 

WARNING 9. EMPTY AOS L U IT i I 9 E G M E N T 
MODULE" lile-name(module-name) 

message. 



Errors 

ERROR SEGMENT COMBINATION ERROR 

SEGMENT: segment-name 

MODULE' fii e -name(module-namel 

The scgmenl is ignored. 

ERR'OR 102: EXTERNALS ATTRIBUTE MISMATCH 
SYMBOL: external-name 
MODULE- nie-name(module-name) 

The specified symbol is ignored. 

ERROR IM. EXTERNAL ATTRIBUTES DO NOT MATCH PUBLIC 
SYMBOL: symbol-name 
MODULE' tiie-name(module-name) 

wi"h the same name. The specified symbol ,s ignored. 
ERROR 104: MULTIPLE PUBLIC DEFINITIONS 
SYMBOL: symbol-name 
MODULE- nie-name(module-name) 
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ERROR 105: PUBLIC REFERS TC IGNORED SEGMENT 
SYMBOL: public-name 
SEGMENT: segment-name 

The specified public symbol is defined referencing ihe specified ignored segment. The 
specified public symbol is ignored. 

ERROR 10 6: SEGMENT OVERFLOW 
SEGMENT: segment-name 

The specified segment, after combination, is larger than the maximum segment size 
allowed for the segment according to its type or to the given locating control. The 
specified segment is ignored. 

ERROR 107: ADDRESS SPACE OVERFLOW 
SPACE: space-name 
SEGMENT: segment name 

RL51 was unable to allocate the specified relocatable segment, according to the 
segment relocation type, in the specified address space. The specified segment is 
ignored. 

ERROR 108: SEGMENT IN LOCATING CONTROL CANNOT BE 

ALLOCATED 
SEGMENT: segment name 

RLM was unable to allocate the specified relocatable segment that appears in the 
locating control, according to the requirements imposed by the locating control and 
according to ihe segment relocation type. The specified segment is ignored. 

ERROR 109: EMPTY RELOCATABLE SEGMENT 
SEGMENT: segment-name 

The specified segment, after combination has zero size. The specified segment is 
ignored. 

ERROR 110: CANNOT FIND SEGMENT 
SEGMENT: segment-name 

The specified segment name occurred ill the command tail hut is not Ihe name of any 
segment defined within the input files. The specified segment is ignored. 

ERROR 111: SPECIFIED BIT ADDRESS NOT ON BYTE BOUNDARY 
SEGMENT: segment-name 

The specified segment was requested in a BIT locating control. The segment is not a 
BIT segment, and the requested address is not on byte boundary. The specified 
segment is ignored. 

ERROR 112: SEGMENT TYPE NOT LEGAL FOR COMMAND 
SEGMENT: segment-name 

The specified segment is not one of the types that are legal for the locating control 
for which it is specified. The specified segment is ignored. 

ERROR 113: RESERVED. 
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ERROR I 2 1 ! IMPROPER f I XUP 
MODULE: file-name(module-name) 
SEGMENT: segment-name 
OFFSET: pseg-offset 

An error occurred in the evaluation of a fixup. An example of this error is when the 
value of the fixup expression does not meet the requirements of the type of the 
referenced location. A fixup is an address that cannot be determined at compile/ 
assembly-time. It is marked as relocatable, and at RL-5 1 lime is assigned an address. 
A fixup is the address assigned to that relocatable symbol. 

FATAL ERROR 2 6 t INVALID FILE NAME- 
partial command 

The file-name specified in the command is not a valid file name. The command is 
repeated up to and including the point or error. 



FATAL ERROR 209: FILE USED IN CONFLICTING CONTEXTS 
FILE: . file-name 

The specified file is used in more than one context, for example, using the same file 
for both input and output. (This may be caused by specifying for the first input file 
a file that has no extension, and not specifying an output file.) 

FATAL ERROR 210: I/O ERROR, INPUT FILE; 
UDI ERROR: EXCEPTION <num>:<ext> 
FILE: file-name 

An I/O error was delected in accessing an input file. The text of the message includes 
a description of the specific I/O error that occurred. See the user's guide for your 
operating system for a list of possible I/O errors. 

FATAL ERROR 211: I/O ERROR, OUTPUT FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing the output file. The text of the message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a list of possible I/O errors. 

FATAL ERROR 212: I/O ERROR, LISTING FILE: ERROR' 
FILE: tile-name 

An I/O error was detected in ss:ng the listing file. The text of the message includes 
a description of the specific I/O error that occurred. See the user's guide for your 
operating system for a list of possible I/O errors. 

FATAL ERROR 213: I/O ERROR, TEMPORARY FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing a temporary file. The text of the message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a list of possible I/O errors. 

FATAL ERROR 214: INPUT PHASE ERROR 
MODULE: lile-name(module-name) 
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* Sff WhCn RL5 ' — «*« two than it r , 1d 

FATAL ERROR MS| CHECK Clin t c r, . . 
MODULE: file-namefmlil^ 

o" a a rea C d erro7 * **" " "» ™ S indicates a bad input module 

2,6 < '"SUFF,C,ENT MEMORY 

The file named ,n the message, judging by its first byte of data, is no, a valid ob,ec, 
^SSr^yST** hMdCr ind '"'« *« <* MM module 

— « required record. This ^A^^JtSSSSST » ' 



P^co™' M ° DULE SPECIFIED MORE THAN ONCE 

55 S^k Sl^-^^-S^ — <*« once. 
KtaUtf' ?2?: SECMENT SPECIFIED MORE THAN ONCE 
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The same keyword appears in the command more lhan once. The command is repealed 
up to and including the point of error. 

FATAL ERROR 225: SEGMENT ADDRESSES ARE NOT IN 
ASCENDING ORDER 

partial command 

The addresses of the segments within one locating control are not in ascending order. 
The command is repeated up lo and including Ihe point of error. 

FATAL ERROR 226: SEGMENT ADDRESS INVALID FOR CONTROL 
partial command 

The address requested for a segment is not valid for the given locating control. The 
command is repeated up lo and including the point of error. 

FATAL ERROR 227: PAGEWIDTH PARAMETER OUT OF RANGE 
partial command 

The PAGEWIDTH parameter given is out of the occeptahle range. 

FATAL ERROR 228: RAMSIZE PARAMETER OUT OF RANGE 
partial command 

The RAMSIZE parameter given is out of acceptable range. 



FATAL ERROR 229: 1/0 ERROR, OVERLAY FILE: ERROR' 
FILE: tile-name 

An I/O error was delected in accessing an overlay file. The text of Ihe message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a lis! of possible I/O errors. (This error occurs only if 
IXREF was requested. Its occurrence does not invalidate Ihe output object file.) 

FATAL ERROR 230: INCOMPATIBLE OVERLAY VERSION 
FILE: lile-name 



The overlay file, although loaded successfully, has a version number that is not the 
one expected by RL51. The possible cause is that the RL5I program and the loaded 
overlay are not of the same version. (This error occurs only if IXREF or OVERLAY 
was requested. If only IXREF was requested. Ihe output object file is valid.) 

FATAL ERROR 231: TOO MANY IXREF ENTRIES 

The number of IXREF entries (entry is a pair consisting of modules and symbol 
reference) is too large to be processed. The IXREF listing step is nol performed. The 
NOLIBRARIES and NOGENERATED controls may be used in order to decrease 
this number and overcome the error. (This error occurs only if IXREF was requested. 
Its occurrence does not invalidate the output object file.) 

FATAL ERROR 232: OVERLAY CONTROL CONFLICTS XREF 
SELECTOR ITEMS 

The overlay control should not appear with the IXREF selector items NOLIBRAR- 
IES or NOGENERATED. 

FATAL ERROR 233: ILLEGAL USE OF • IN OVERLAY 
CONTROL 
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ineuseof > • or • ) * wilh the OVERLAY control is illegal. 

'ATAL ERROR 240: INTERNAL PROCESS ERROR 

wUhi'n RLM eleCted tha ' " h3S made « -o, This error indicate, a bug 



LIB51 Command Summary 




Table C-l. LI B5 1 Commands 



Command 


Abbreviation 


Description 


ADD ( liie|(module|. .|)| > (.. .] TO library Me 


A 


Adds modules lo a 
library 


CREATE library file 


C 


Creates a library 

lile 


DELETE library Jile(module|... |) 


D 


Deieles modules 
Irom a library 


EXIT 


E 


Terminates 
session with 
LIB5I 


EXTRACT < liie[(module[....])| > [,...] TO file 


X 


Extracts modules 
Irom libraries 


HELP 


H 


Displays syntax ol 
LIB96 commands 


LIST <lne|(moduie|. .|)|> |....| |TO fiie| |PUBLICS| 


L[P| 


Lists modules 
contained in librar- 
ies, and optionally 
lists all publics 


REPLACE < lile||module|. . Ill > |....| IN library. die 


R 


Replaces modules 
in a library 




LIB51 Error Messages 



D 



INSUFFICIENT MEMORY 

L1B5I cannot execute the command because it requires more memory than the amount 
of memory available in the system. 

I NVAL ID SYNTAX 

The command was not entered properly. Reenter it using the correct syntax. 
UNRECOGN I ZED COMMAND 

An illegal or misspelled command was entered. The only commands are ADD, 
CREATE. DELETE. EXIT. EXTRACT. HELP, LIST. REPLACE, and their 
respective abbreviations. 

INVALID MODULE NAME 

The specified module name contains an invalid character or starts with a digit. 

MODULE NAME TOO LONG 

The specified module name exceeds 40 characters. 

RIGHT PARENTHESIS EXPECTED 

A ")" is missing in the command. 

pathname , CHECKSUM ERROR 

The specified file has an error in one of its checksum fields. This is usually the result 
of an I/O error. 

pathname , ILLEGAL RECORD FORMAT 

This error is usually caused by an I/O error or a translation error. 

pathname, BAD RECORD SEQUENCE 

This error is usually caused by an I/O error or a translation error. 

pathname , DUPLICATE SYMBOL IN INPUT 

You have attempted to ADD or REPLACE a module that contains a public symbol 
that is already within the library. 

pathname , ATTEMPT TO ADD DUPLICATE MODULE 
The specified module name already appears within the library. 
pathname, FILE ALREADY EXISTS 

The specified file in the CREATE command already exists Chow iiother ntne 

for the litttt} 
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pathname , NOT LIBRARY 

The specified file is not a library. 

The TO filename is omitted in the ADD command. 

UNRECOGNIZED COMMAND 

An illegal or misspelled command was entered. The only legal commands are ADD. 
CREATE. DELETE, LIST, and EXIT. 

File or Module Errors 

The following errors indicate that there is some problem with the file or module 
spec.fied. There is no partial copy or the command given with these error messages. 

FILE ALREADY EXISTS 

The file specified in the CREATE command already exists. Choose a new name for 
the library. 

filename, DUPLICATE SYMBOL IN INPUT 

You have attempted to add a file thai contains a PUBLIC symbol already within the 
library. 

filename , NOT LIBRARY 
The specified file is not a library. 
filename t modname ) : NOT FOUND 

You have attempted to delete a module that docs not exist. Check for misspelling of 
the filename or module name. 

rnodrutme-ATTEMPT TO ADD DUPLICATE MODULE 
The specified module name already appears within the library. 
symbol — ALREADY IN LIBRARY 

You have attempted to add a module that contains a PUBLIC symbol that is already 
in the library. 

filename. CHECKSUM ERROR 

filename. OBJECT R E C D R D TOO SHORT 

filename. ILLEGAL RECORD FORMAT 

L1B51 cannot process the specified file because it is not a legal object file. Possible 
cause is a file damage or translator error. 



Hexadecimal-Decimal Conversion Table 




Tabic E-i is for hexadecimal to decimal and decimal lo hexadecimal conversion. To 
find the decimal equivalent of a hexadecimal number, locate the hexadecimal number 
in the correct position and note the decimal equivalent. Add the decimal numbers. 

To find the hexadecimal equivalent of a decimal number, locate the next lower decimal 
number in the table and note the hexadecimal number and its position. Subtract the 
decimal number shown in the table from the starting number, f ind the difference in 
the table Continue this process until there is no difference. 



Table E-l . Hexadecimal-Decimal Conversion Table 



Molt Significant Byte 


Least Significant Byte 


Digit 4 


Dlgll 3 


Digit 2 


Digit 1 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 


























1 


4 096 


1 


256 


1 


16 


1 


1 


2 


S 192 


2 


512 


2 


32 


2 


2 


3 


12 2B8 


3 


768 


3 


48 


3 


3 


4 


16 3B4 


4 


1 024 


4 


64 


4 


4 


5 


20 480 


5 


1 280 


s 


80 


5 


5 


6 


24 5?6 


6 


1 536 


6 


96 


6 


6 


7 


28 672 


7 


1 792 


7 


112 


7 


7 


e 


32 768 


8 


2 048 


8 


128 


8 


8 


9 


36 864 


9 


2 304 


9 


144 


9 


9 


A 


40 960 


A 


2 560 


A 


160 


A 


10 


B 


45 056 


B 


2 816 


B 


176 


B 


11 


C 


49 152 


C 


3 072 


C 


192 


C 


12 


D 


53 248 


D 


3 328 


D 


208 


D 


13 


E 


57 344 


E 


3 548 


E 


224 


E 


14 


F 


61 440 


F 


3 840 


F 


240 


F 


15 



\ 

■ 



abbreviations. 3-14. A-5 
absolute object Tile. 4-5 
absolute object module. 1-2 
absolute segments. 2-2 
ADD. 6-2 
address. 3-2 
address spaces. 2-3. 2-4 
allocation. 3-8 
allocation process. 2-3 
assembler (ASM.M). 1-3. 5-1 

BIT. 2-2. 2-3. 2-4. 3-0. 
BITADDRESSABLE. 2-2. 2-3 
BLOCK. 2-2 

CODE. 2-2. 2-3. 3-9 
command entry. 3-1 
command, invocation. 

ire invocation command 
comments. 3-2 
configuration controls. 3-1 I 
console display. 4-1 
continuation lines. 3-2 
control-list. 3-1 
controls. 3-4 

see also linking controls, listing controls. 

locating controls 
CREATE. 6-4 

DATA. 2-2. 2-3. 3-9 
DEBUG control. 1-3, 3-4 
debugging, i-l 
DEBUG LINES. 3-7 
DEBUGPUBLICS. 3-7 
DEBUGSYMBOLS. 3-7 
DELETE. 6-5 

development process. I-l. 1-2 
device. 3-2 

editor, test. 1-3 

error messages. 4-4. B-l D-l 

EXIT. 6-6 

external references. 2-4 
filename. 3-2 

henadccimal-decimal conversion, E-l 

1CE-51 in-circuit emulator. 1-3 
IDATA. 2-2. 2-3. 3-9 
in-circuit emulator. 

see ICE-51 in-circuit emulator 
IN PAGE. 2-2 
inpui-iist. 3-1 . 3.2 
invocation command. 3-2. 6-1 

address. 3-2 

control-list. 3-1 

device. 3-2 

filename. 3-2 



input-list. 3-1, J-2 
module-name. 3-2 
name. 3-2 
output-file. 3-3 
pathname. 3-2 
segment-name. 3-2 
IXREF. 4-4. 4-5 

LIB5I. 6-1 
error messages. D-l. D-2 

LINES. 3-5, 3-6. 3-15 

linking cuntrols. 3-8. A-3 
NAME. 3-7 

linking switches. 3-7 
DEBUGLINES. 3-7. 3-8 
DEBUGPUBLICS. 3-7. 3-8 
DEBUGSYMBOLS. 1-7 3-8 
NO DEBUG LINES, 3-8 
NODEBUCPUBLICS, 3-8 
NO DEBUGSYMBOLS. 3-8 

link summary. 4-1 

LIST. 6-9 

listing controls. 3-4. A-3 

DEBUG control. 3-7 

listing file. 3-4 
listing file. 4-1 
listing switches. 3-6 

IXREF. J-4. 4-5 

LINES. 3-5. 3-6 

MAP. 3-5. 3-6 

NOLINES. 3-6 

NOMAP, 3-6 

NOPUBLICS. 3-6 

NOSYMBOLS. 3-6 

PUBLICS. 3-5. 3-6 

SYMBOLS. 3-5. 3-6 
locating controls. 3-8. 3-9. 5-16 A-4 

BIT. 3-9 

CODE, 3-9 

DATA. 3-9 

IDATA. 3-9 

PRECEDE, 3-9. 5-16 
STACK, 3-0 
XDATA, 3-9 

major functions, 2-1 
MAP. 3-5. 3-6 
memory map. 3-4 
modifying, 1-1 
module, 1-2. 2-1 
modular programming. 1-1 
module-name. 3-2 

NAME. 3-7 
name. 3-2 

NODEBUGLINES. 1-8 
NODEBUGPUBLICS. 3-8 
NODEBLGSYMBOLS. 3-8 
NOIXREF, 3-6 
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NOLINKS. M 
NOMA I'. 3-6 
NOOVER1.AY. 3-U. 3-I2 
NOPRINT. 3-5 
NOPUBI.ICS. 3-6 
NOSYMBOLS. 3-6 
nolalion. A- 1 

output-file. 3-3 
OVERLAY. 3-H.3-12 

PAGE. 2-2. 2-3 
partial segments. 2-2 
pathname. 3-2 
PRECEDE. 3-9. 5-16 
PRINT. 3-4 
program. 1-2 

program development, l-l. 1-2 
PROM programmer. I-I 
PUBLICS. 3-5. 3-6 



RAMM/I-. S-1 1 
relocatable segments. 2-2. 2-3 
relocation. 1-3. 2-2 
HUt. 1-2. 2-1. 2-2. 3-1. 5-1 

command format. A-l 

controls. 3-4. A-3 

error messages. B-l 

pass. 2-2 

segment. 1-2. 2-2 
segment-name. 3-2 
segment type, absolute. 2-2 
segment tvpe. relocatable. 2-2. 2-3 
STACK. 2-2. 2-3 
SYMBOLS. 3-5. 3-6 
symbol table. 4-3 

UNIT. 2-2. 2-3 

XDATA. 2-2. 2-3. 3-9 



• * * 
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REQUEST FOR READER'S COMMENTS 



Please use this form to help us evaluate the eflectiveness ol this manual and improve the quality of tuture documents 

(Please limit your comments to documentation.) 

To order publications, contact the Intel Literature Department (see page li ot this manual). 
Indicate the type ol user/reader you most nearly represent: 

□ Software engineering manager □ Student programmer 

□ Systems engineer □ Other (please specify) 

□ Application programmer 

Indicate the application for which you use this product: 



How do you use this manuaP 

Q As a reference manual □ Other (please specify) 

□ As an introduction to the sub|ect _! 

Fill in the squares below with a rating of 5 (excellent) to 1 (poor); use the lines provided tor additional comments. 

CH Accuracy. Cite any instances of inaccuracies. 



Q Organization. Could you find the information you needed' 



CD Thoroughness. Are product features fully explained 7 



CH Readability. Is the writing style clear? _ 
Examples. Are there enough examples 9 



CH Level. Is the manual too easy or too difficult? . 
CH Overall. How would you improve this manual 7 



List specific points that need clarification: 
Page Problem 



Your Name Job Title 

Company Name 

Street Address 

City State Zip 

CD Check here if you want a written reply. 



